前端工程化全景：从代码规范到 CI/CD 流水线

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'
  - '!**/dist/**'
  - '!**/node_modules/**'

// package.json（根）
{
  "name": "@my-org/root",
  "private": true,
  "packageManager": "pnpm@10.2.0",
  "scripts": {
    "dev:web": "pnpm --filter @my-org/web dev",
    "dev:admin": "pnpm --filter @my-org/admin dev",
    "build": "pnpm -r build",
    "test": "pnpm -r test",
    "lint": "pnpm -r lint",
    "clean": "pnpm -r exec rm -rf node_modules dist .turbo"
  },
  "devDependencies": {
    "turbo": "^2.3.0"
  }
}

// turbo.json（Turborepo 配置）
{
  "$schema": "https://turbo.build/schema.json",
  "globalDependencies": ["**/.env.*local"],
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    },
    "lint": {},
    "test": {},
    "dev": {
      "cache": false,
      "persistent": true
    }
  }
}

# 安装全部依赖（ monorepo 根）
pnpm install

# 安装单个包到某个 workspace
pnpm --filter @my-org/web add axios

# 安装 devDependency
pnpm add -D typescript --filter @my-org/ui

# 运行 workspace 脚本
pnpm --filter @my-org/web run build

# 批量运行
pnpm -r run lint

# 依赖分析
pnpm why lodash
pnpm list --depth=0

# Vue 3 项目初始化
pnpm create vite@latest my-vue-app -- --template vue-ts
cd my-vue-app
pnpm install -D eslint @eslint/js typescript-eslint eslint-plugin-vue

// eslint.config.js (Flat Config — ESLint v9+)
import js from '@eslint/js';
import ts from 'typescript-eslint';
import vue from 'eslint-plugin-vue';
import prettier from 'eslint-config-prettier';

export default [
  js.configs.recommended,
  ...ts.configs.recommended,
  ...vue.configs['flat/recommended'],
  {
    files: ['**/*.{ts,tsx,vue}'],
    languageOptions: {
      parserOptions: { project: './tsconfig.json' }
    },
    rules: {
      '@typescript-eslint/no-explicit-any': 'warn',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
      'vue/multi-word-component-names': 'off',
      'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off'
    }
  },
  prettier // 关闭与 Prettier 冲突的规则
];

// prettier.config.js
export default {
  semi: true,
  singleQuote: true,
  tabWidth: 2,
  trailingComma: 'es5',
  printWidth: 100,
  arrowParens: 'avoid',
  endOfLine: 'lf',
  plugins: ['prettier-plugin-tailwindcss'] // 自动排序 Tailwind classes
};

# 格式化全部
npx prettier --write .

# 检查（CI 中用）
npx prettier --check .

# 安装
pnpm add -D husky lint-staged

# 初始化 husky（v9+）
npx husky init

// package.json
{
  "lint-staged": {
    "*.{js,ts,vue,jsx,tsx}": ["eslint --fix", "prettier --write"],
    "*.{css,scss,json,md}": ["prettier --write"]
  }
}

# .husky/pre-commit（Husky v9 自动生成，或手动配置）
echo "npx lint-staged" > .husky/pre-commit

# .husky/commit-msg（提交信息规范检查）
echo 'npx commitlint --edit ${1}' > .husky/commit-msg

pnpm add -D @commitlint/config-conventional @commitlint/cli

// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'chore', 'ci', 'build', 'revert'
    ]],
    'subject-case': [0]
  }
};

1. 从 main 创建 feature 分支
   git checkout -b feat/user-profile-page

2. 开发并提交（遵循 commitlint 规范）
   git commit -m "feat: 新增用户资料页面布局"

3. 推送并创建 Pull Request
   git push origin feat/user-profile-page
   → GitHub 上点击 "Create Pull Request"

4. CI 自动运行（Lint / Test / Build）
   → 全部通过方可合并

5. Code Review（最小 1 人 Approve）
   → Reviewer 检查逻辑、测试、性能影响

6. Squash & Merge 到 main
   → 保持 main 历史线性清晰

7. 自动触发部署流水线

# .github/settings.yml（或通过 UI 配置）
branches:
  - name: main
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 1
      required_status_checks:
        strict: true
        contexts:
          - lint
          - test
          - build
      enforce_admins: false
      required_linear_history: true

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: '10.2.0' }
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'pnpm' }
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: '10.2.0' }
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'pnpm' }
      - run: pnpm install --frozen-lockfile
      - run: pnpm test:unit --coverage
      - uses: codecov/codecov-action@v5
        with: { token: ${{ secrets.CODECOV_TOKEN }} }

  build:
    runs-on: ubuntu-latest
    needs: [lint, test]
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: '10.2.0' }
      - uses: actions/setup-node@v4
        with: { node-version: '22', cache: 'pnpm' }
      - run: pnpm install --frozen-lockfile
      - run: pnpm build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Vercel (Staging)
        run: npx vercel --token ${{ secrets.VERCEL_TOKEN }} --yes

  deploy-production:
    runs-on: ubuntu-latest
    needs: deploy-staging
    environment: production  # 需要人工审批
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Vercel (Production)
        run: npx vercel --prod --token ${{ secrets.VERCEL_TOKEN }} --yes

# Dockerfile（多阶段构建）
# ---- 构建阶段 ----
FROM node:22-alpine AS builder
WORKDIR /app
RUN corepack enable && corepack prepare pnpm@10.2.0 --activate
COPY pnpm-lock.yaml package.json pnpm-workspace.yaml ./
COPY packages ./packages
COPY apps/web ./apps/web
RUN pnpm install --frozen-lockfile
RUN pnpm --filter @my-org/web run build

# ---- 运行阶段 ----
FROM nginx:alpine
COPY --from=builder /app/apps/web/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

# nginx.conf（SPA 配置）
server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 静态资源强缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

.env                  # 默认（不提交 Git）
.env.local            # 本地覆盖（.gitignore）
.env.development      # dev 服务器
.env.staging          # 预发布
.env.production       # 生产

# Vite 环境变量（必须以 VITE_ 前缀暴露给客户端）
VITE_API_BASE_URL=https://api.example.com
VITE_APP_NAME=MyApp
VITE_SENTRY_DSN=https://xxx@xxx.ingest.sentry.io/xxx

# 服务端专用（无前缀）
DATABASE_URL=postgresql://...

// config/features.ts
export const features = {
  newDashboard: import.meta.env.VITE_FF_NEW_DASHBOARD === 'true',
  betaPayment: import.meta.env.VITE_FF_BETA_PAYMENT === 'true',
} as const;

// 使用
import { features } from '@/config/features';

function App() {
  return (
    <>
      {features.newDashboard ? <NewDashboard /> : <OldDashboard />}
    </>
  );
}

// vite.config.ts（Vue 项目）
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import { resolve } from 'path';

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: { '@': resolve(__dirname, 'src') }
  },
  build: {
    target: 'es2022',
    minify: 'terser',
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['vue', 'vue-router', 'pinia'],
          ui: ['element-plus'] // 或 'ant-design-vue' / 'vuetify'
        }
      }
    }
  },
  server: {
    port: 3000,
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true
      }
    }
  }
});