1. 前端项目规范概述

• 1. 项目选型
• 2. 工具要求
  • 2.1 使用 NVM 管理 Node.js 版本
  • 2.2 corepack - 包管理器的管理器
  • 2.3 使用 pnpm
• 3. 项目要求
• 4. 针对 Nuxt 3 项目的要求
• 5. Docker 镜像选型和构建
  • 5.1 静态项目 Dockerfile 示例
  • 5.2 Nuxt 3 项目 Dockerfile 示例

1. 项目选型

推荐优先使用 Vue 3 来开发，接着是 React。

Vue 3 项目优先使用 Nuxt 3 开发，不仅仅用于 SSR，还可以用于静态站点、后台管理等项目。

Nuxt 3 选型考量

为什么使用 Nuxt 来搭建后台/中台？后台有 SEO 要求吗？

答：Nuxt 3 作为一个全栈框架，并非定义为单纯为 SEO 而生的框架。我们基于 Nuxt 3 的考量是快速、简单，并且能在静态生成、服务端渲染、客户端渲染之间无缝切换和混合，还能通过边缘服务器提供服务能力。

2. 工具要求

2.1 使用 NVM 管理 Node.js 版本

使用 NVM 管理 Node.js 版本，防止 Node.js 版本混乱。目前使用 Node.js 22 LTS 版本。

安装 NVM：

winget install CoreyButler.NVMforWindows

安装最新 LTS 版本的 Node.js：

nvm install --lts

2.2 corepack - 包管理器的管理器

使用 corepack 来管理 Node.js 的各种包管理器。

corepack enable
corepack install -g pnpm@latest
corepack install -g yarn@latest
corepack install -g npm@latest

2.3 使用 pnpm

使用 pnpm，并且总是优先使用 pnpm 的最新版本。

截至目前，pnpm 已经能适应几乎所有项目，其拥有极致的速度，能够节省大量空间，且原生支持 Workspaces（monorepo）。因此没有必要使用 pnpm 以外的包管理器。

3. 项目要求

• 项目必须提供 .editorconfig 用于统一编辑器配置，标准如下：

  root = true
  
  [*]
  indent_size = 2
  indent_style = space
  end_of_line = lf
  charset = utf-8
  trim_trailing_whitespace = true
  insert_final_newline = true

• 项目必须使用 TypeScript 来开发，禁止纯 JavaScript 项目
• 优先使用 ESLint 来进行代码检查，减少或停止使用 Prettier

4. 针对 Nuxt 3 项目的要求

单个根标签

解释：虽然 Vue 3 不再需要根标签，但 Nuxt 的许多特性依然需要原生的根标签来实现。

• 所有的单文件组件必须使用 <script setup lang="ts"> 开头，以便于使用 Vue 3 的新特性
• 每个组件必须有一个根标签，推荐直接使用 <div> 标签，不能使用非原生标签

  <script setup lang="ts">
  // ...
  </script>
  
  <template>
    <div>
      <!-- ... -->
    </div>
  </template>

5. Docker 镜像选型和构建

拉取当前推荐的版本：

docker pull node:22.11.0

精简版本：

docker pull node:22.11.0-alpine3.20

构建使用的版本：

docker pull node:22.11.0-bookworm

发布版本：

docker pull node:22.11.0-bookworm-slim

5.1 静态项目 Dockerfile 示例

下面提供一个 Dockerfile 样例，这是一个纯 Vue 3 项目，使用多阶段构建，第一阶段使用构建版本的镜像，安装项目依赖并构建项目。第二阶段使用精简版本的镜像，直接复制第一阶段的产物。

建议配置 nginx.conf 文件，以便于更好的控制 Nginx 服务器。

server {
  listen 8080 default_server;
  server_name _;
  absolute_redirect off;

  location / {
    root /usr/share/nginx/html;
    try_files $uri $uri/ @router;
    index index.html;
  }

  location @router {
    rewrite ^.*$ /index.html last;
  }
}

下面是 Dockerfile 样例：

ARG NODE_VERSION=22.11.0
ARG NPM_REGISTRY=https://registry.npmjs.org
ARG DEBIAN_MIRROR=deb.debian.org

# Builder image
FROM node:${NODE_VERSION}-bookworm as builder
ARG NPM_REGISTRY
ENV NODE_OPTIONS=--max-old-space-size=4096
WORKDIR /app

COPY package.json pnpm-lock.yaml ./

RUN npm -v && \
    npm config set registry ${NPM_REGISTRY} && \
    npm install -g pnpm && \
    pnpm -v && \
    pnpm config set registry ${NPM_REGISTRY} && \
    pnpm install --ignore-scripts

COPY . ./

RUN pnpm install && pnpm build

# Nginx Server
FROM nginx:1.27.3-alpine3.20-slim
WORKDIR /usr/share/nginx/html/
COPY --from=builder /app/dist/ ./
COPY ./docker/nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 8080
CMD ["nginx", "-g", "daemon off;"]

5.2 Nuxt 3 项目 Dockerfile 示例

下面是一个 Nuxt 3 项目的 Dockerfile 样例：

ARG NODE_VERSION=22.11.0
ARG NPM_REGISTRY=https://registry.npmjs.org
ARG DEBIAN_MIRROR=deb.debian.org

# Builder image
FROM node:${NODE_VERSION}-bookworm as builder
ARG NPM_REGISTRY
ENV NODE_OPTIONS=--max-old-space-size=4096
WORKDIR /app

COPY package.json pnpm-lock.yaml ./

RUN npm -v && \
    npm config set registry ${NPM_REGISTRY} && \
    npm install -g pnpm && \
    pnpm -v && \
    pnpm config set registry ${NPM_REGISTRY} && \
    pnpm install --ignore-scripts

COPY . ./

RUN pnpm install && pnpm build

# Runtime image
FROM node:${NODE_VERSION}-bookworm-slim
WORKDIR /app

COPY --from=builder /app/.output/ ./.output/

EXPOSE 3000
CMD ["node", "./.output/server/index.mjs"]