CI/CD 与部署实践

一、前端 CI/CD 流程全景

1.1 完整流水线

前端 CI/CD 流水线分为代码提交 → 代码检查 → 测试 → 构建 → 部署 → 通知六个阶段，每个阶段承担不同的质量保障职责。

开发提交代码
    │
    ▼
┌─────────────────────────────────────────────────────┐
│ 1. 代码检查 (Lint)                                   │
│    ├── ESLint — JavaScript/TypeScript 语法检查       │
│    ├── Prettier — 代码格式检查                       │
│    ├── Stylelint — 样式规范检查                      │
│    └── TypeScript 类型检查 (tsc --noEmit)            │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│ 2. 自动化测试 (Test)                                 │
│    ├── 单元测试 (Vitest / Jest) + 覆盖率报告          │
│    ├── 组件测试 (Testing Library)                    │
│    └── E2E 测试 (Playwright)                        │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│ 3. 构建 (Build)                                     │
│    ├── 多环境构建 (dev / test / staging / production) │
│    ├── 产物哈希 (content hash)                       │
│    └── Docker 镜像构建                               │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│ 4. 部署 (Deploy)                                    │
│    ├── 静态资源 → CDN                                │
│    ├── 容器镜像 → K8s / Docker                       │
│    └── 全量/灰度发布                                 │
└──────────────────────┬──────────────────────────────┘
                       ▼
┌─────────────────────────────────────────────────────┐
│ 5. 通知 (Notify)                                    │
│    ├── 飞书/钉钉/企微机器人通知                       │
│    ├── 构建状态 + 部署链接                           │
│    └── 测试报告 / 覆盖率变化                         │
└─────────────────────────────────────────────────────┘

1.2 各阶段责任人

1.3 流水线配置原则

# 关键原则：快速反馈 + 逐步放行

# 原则一：按阶段分级，防止"一错到底"
# - Lint 失败 → 不跑测试
# - 测试失败 → 不构建
# - 构建失败 → 不部署

# 原则二：区分 PR 和 Merge
# - PR 阶段：Lint + 测试（快速反馈）
# - Merge 后：构建 + 部署（完整流水线）

# 原则三：环境隔离
# - dev：自动部署（无需审批）
# - staging：部署需审批
# - production：部署需审批 + 时间窗口

踩坑点

二、代码质量检查

2.1 工具链全景

现代前端项目通常组合使用以下工具形成代码质量防线：

2.2 ESLint + Prettier 配置

// ---------- .eslintrc.cjs ----------
// 现代 ESLint Flat Config 风格（ESLint >= 9.0）

const eslintConfig = [
  // ... 省略基础配置

  // 生产代码禁止 console.log（允许 warn/error）
  {
    rules: {
      'no-console': ['warn', { allow: ['warn', 'error'] }],
      'no-debugger': 'error',
      // 禁止未使用的变量
      '@typescript-eslint/no-unused-vars': ['error', {
        argsIgnorePattern: '^_',
        varsIgnorePattern: '^_',
      }],
    },
  },
]

// ---------- .prettierrc ----------
{
  "semi": false,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "always",
  "endOfLine": "lf"
}

// ---------- package.json 脚本 ----------
{
  "scripts": {
    "lint": "eslint . --max-warnings 0",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "typecheck": "tsc --noEmit",
    "stylelint": "stylelint \"**/*.{css,scss,vue}\""
  }
}

✅ 推荐 vs ❌ 不推荐

# ✅ CI 中强制检查
eslint . --max-warnings 0
# 如果有任何 warning，也会导致 CI 失败，严格要求

# ❌ 忽略 warning
eslint . 
# warning 不会导致 CI 失败，易导致代码质量逐步下降

# ✅ 分阶段检查
# .husky/pre-commit
npx lint-staged

# CI 中做全量检查
eslint . --max-warnings 0

# ❌ 本地全量检查
# 大项目全量检查太慢，开发者会绕过 husky

2.3 Husky + lint-staged 自动化

# ---------- 初始化 ----------
npm install -D husky lint-staged
npx husky init

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

# ---------- .husky/pre-commit ----------
npx lint-staged

# ---------- .husky/commit-msg ----------
npx --no -- commitlint --edit "$1"

2.4 Commitlint 配置

// ---------- commitlint.config.js ----------
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'refactor', 'perf', 'style', 'test',
      'docs', 'chore', 'ci', 'revert',
    ]],
    'scope-case': [2, 'always', 'kebab-case'],
    'subject-case': [2, 'always', 'lower-case'],
    'subject-empty': [2, 'never'],
    'type-empty': [2, 'never'],
    'header-max-length': [2, 'always', 72],
  },
}

踩坑点

2.5 CI 中的代码检查配置

# ---------- GitHub Actions：Lint Job ----------
name: Code Quality Check
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      # 类型检查
      - name: TypeScript Type Check
        run: npx tsc --noEmit

      # ESLint 检查
      - name: ESLint
        run: npx eslint . --max-warnings 0

      # Prettier 格式检查
      - name: Prettier Check
        run: npx prettier --check .

      # Stylelint 样式检查
      - name: Stylelint
        run: npx stylelint "**/*.{css,scss,vue}"

三、自动化测试在 CI

3.1 单元测试 + 覆盖率报告

// ---------- package.json ----------
{
  "scripts": {
    "test": "vitest run",
    "test:coverage": "vitest run --coverage",
    "test:watch": "vitest"
  }
}

// ---------- vitest.config.ts ----------
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./tests/setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json-summary', 'lcov'],
      // 覆盖率门槛
      thresholds: {
        statements: 80,
        branches: 75,
        functions: 80,
        lines: 80,
      },
      // 排除非业务代码
      exclude: [
        'src/main.ts',
        'src/router/**',
        'src/types/**',
        'src/**/*.d.ts',
        'tests/**',
      ],
    },
  },
})

覆盖率门槛对比

# ---------- GitHub Actions：Test Job ----------
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      - name: Run Unit Tests
        run: npx vitest run --coverage

      # 上传覆盖率报告
      - name: Upload Coverage Report
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

      # 可选：上传到 Codecov / Coveralls
      - name: Upload to Codecov
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

3.2 E2E 测试（Playwright）

# ---------- 安装 Playwright ----------
npm install -D @playwright/test
npx playwright install chromium

// ---------- playwright.config.ts ----------
import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 1 : 0,
  workers: process.env.CI ? 2 : undefined,
  reporter: [
    ['html', { outputFolder: 'playwright-report' }],
    ['json', { outputFile: 'playwright-report/results.json' }],
  ],
  use: {
    baseURL: process.env.BASE_URL || 'http://localhost:4173',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
})

// ---------- e2e/login.spec.ts 示例 ----------
import { test, expect } from '@playwright/test'

test.describe('登录流程', () => {
  test('用户可以使用有效凭证登录', async ({ page }) => {
    await page.goto('/login')

    // 填充登录表单
    await page.fill('[data-testid="username"]', 'admin')
    await page.fill('[data-testid="password"]', 'password123')
    await page.click('[data-testid="login-button"]')

    // 等待跳转到仪表盘
    await expect(page).toHaveURL('/dashboard', { timeout: 10000 })
    await expect(page.locator('[data-testid="welcome"]')).toContainText('欢迎回来')
  })

  test('无效凭证应该显示错误提示', async ({ page }) => {
    await page.goto('/login')
    await page.fill('[data-testid="username"]', 'admin')
    await page.fill('[data-testid="password"]', 'wrong')
    await page.click('[data-testid="login-button"]')

    await expect(page.locator('[data-testid="error-message"]'))
      .toBeVisible()
    await expect(page).toHaveURL('/login')
  })
})

E2E 测试在 CI 中的配置

# ---------- GitHub Actions：E2E Test Job ----------
jobs:
  e2e:
    timeout-minutes: 15
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - run: npm ci

      # 构建生产版本
      - run: npm run build

      # 启动预览服务器（后台运行）
      - name: Start Preview Server
        run: npx vite preview --port 4173 &

      # 安装 Playwright 浏览器
      - name: Install Playwright Browsers
        run: npx playwright install chromium

      # 运行 E2E 测试
      - name: Run E2E Tests
        run: npx playwright test

      # 上传测试报告（测试失败时也上传）
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 7

踩坑点

3.3 可视化回归测试

可视化回归测试用于检测 UI 样式的非预期变化，通常配合 Storybook 使用。

# ---------- GitHub Actions：Chromatic ----------
name: Visual Regression

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Chromatic 需要完整历史

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci

      - name: Publish to Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          token: ${{ secrets.GITHUB_TOKEN }}

// ---------- Playwright 截图对比（自建方案）----------
import { test, expect } from '@playwright/test'

test.describe('可视化回归测试', () => {
  test('登录页面布局', async ({ page }) => {
    await page.goto('/login')

    // 等待页面完全加载
    await page.waitForLoadState('networkidle')

    // 与 baseline 截图对比
    await expect(page).toHaveScreenshot('login-page.png', {
      maxDiffPixels: 100,  // 允许最大差异像素数
      threshold: 0.1,      // 像素差异阈值
    })
  })
})

四、构建与产出

4.1 多环境构建

现代前端项目通常需要针对不同环境进行差异化构建。

// ---------- Vite 多环境配置 ----------
// src/utils/env.ts
// 防御：永远不要信任 process.env，做运行时校验

interface EnvConfig {
  apiBaseUrl: string
  appTitle: string
  sentryDsn?: string
  enableDevTools: boolean
  logLevel: 'debug' | 'info' | 'warn' | 'error'
}

function validateEnv(): EnvConfig {
  // 防御：运行时校验必需环境变量
  const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
  if (!apiBaseUrl) {
    throw new Error('VITE_API_BASE_URL 未配置，请检查 .env 文件')
  }

  return {
    apiBaseUrl,
    appTitle: import.meta.env.VITE_APP_TITLE || 'Default App',
    sentryDsn: import.meta.env.VITE_SENTRY_DSN,
    enableDevTools: import.meta.env.VITE_ENABLE_DEVTOOLS === 'true',
    logLevel: (import.meta.env.VITE_LOG_LEVEL as EnvConfig['logLevel']) || 'info',
  }
}

export const env = validateEnv()

# ---------- .env 文件示例 ----------
# .env.development（本地开发）
VITE_API_BASE_URL=http://localhost:8080/api
VITE_APP_TITLE=Dev
VITE_ENABLE_DEVTOOLS=true
VITE_LOG_LEVEL=debug

# .env.staging
VITE_API_BASE_URL=https://staging-api.example.com/api
VITE_APP_TITLE=Staging
VITE_ENABLE_DEVTOOLS=false
VITE_LOG_LEVEL=info

# .env.production
VITE_API_BASE_URL=https://api.example.com/api
VITE_APP_TITLE=Production
VITE_SENTRY_DSN=https://xxx@sentry.io/xxx
VITE_ENABLE_DEVTOOLS=false
VITE_LOG_LEVEL=error

// ---------- package.json ----------
{
  "scripts": {
    "build": "vite build",
    "build:test": "vite build --mode test",
    "build:staging": "vite build --mode staging",
    "build:prod": "vite build --mode production"
  }
}

4.2 产物哈希策略

// ---------- vite.config.ts ----------
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  build: {
    // 文件指纹：内容哈希，保证非覆盖式发布
    rollupOptions: {
      output: {
        entryFileNames: 'assets/[name].[hash:8].js',
        chunkFileNames: 'assets/[name].[hash:8].js',
        assetFileNames: 'assets/[name].[hash:8][extname]',
      },
    },
    // 代码分割
    splitChunks: {
      chunks: 'all',
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name: 'vendor',
          priority: 10,
        },
        elementPlus: {
          test: /[\\/]node_modules[\\/]element-plus[\\/]/,
          name: 'element-plus',
          priority: 20,
        },
      },
    },
  },
})

构建产物目录结构

dist/
├── index.html                      # 入口 HTML（不缓存或协商缓存）
├── assets/
│   ├── index.a1b2c3d4.js           # 应用入口 JS（Hash 命名）
│   ├── vendor.e5f6g7h8.js          # 第三方依赖
│   ├── element-plus.i9j0k1l2.js    # UI 框架单独分包
│   ├── styles.m3n4o5p6.css         # 样式文件
│   └── logo.q7r8s9t0.svg           # 静态资源
└── favicon.ico

4.3 Docker 镜像构建

Dockerfile 最佳实践（多阶段构建）

# ---------- Dockerfile ----------
# ===== 构建阶段 =====
FROM node:20-alpine AS builder

# 安全：使用非 root 用户
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --frozen-lockfile

COPY . .

# 构建
ARG BUILD_MODE=production
RUN npm run build:${BUILD_MODE}

# ===== 运行阶段 =====
FROM nginx:1.25-alpine AS runner

# 安全：使用非 root 用户运行
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nginx -u 1001

# 从构建阶段复制产物
COPY --from=builder /app/dist /usr/share/nginx/html

# Nginx 配置
COPY nginx.conf /etc/nginx/conf.d/default.conf

# 安全：修改权限
RUN chown -R nginx:nginx /usr/share/nginx/html && \
    chmod -R 755 /usr/share/nginx/html

USER nginx

EXPOSE 80

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget -q --spider http://localhost/ || exit 1

CMD ["nginx", "-g", "daemon off;"]

Dockerfile 方案对比

# ---------- docker-compose.yml ----------
version: '3.8'

services:
  frontend:
    build:
      context: .
      args:
        BUILD_MODE: production
    image: my-frontend:${VERSION:-latest}
    ports:
      - "80:80"
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost/"]
      interval: 30s
      timeout: 3s
      retries: 3

4.4 Nginx 配置最佳实践

# ---------- nginx.conf ----------
server {
    listen 80;
    server_name example.com;

    # Gzip 压缩
    gzip on;
    gzip_min_length 1000;
    gzip_types text/plain text/css application/json application/javascript
               text/xml application/xml text/javascript image/svg+xml;
    gzip_vary on;
    gzip_comp_level 6;

    # 根目录
    root /usr/share/nginx/html;
    index index.html;

    # ===== SPA 路由 fallback =====
    location / {
        try_files $uri $uri/ /index.html;
    }

    # ===== 静态资源缓存策略 =====
    # 带 Hash 的文件：长期缓存（1 年）
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # HTML 文件：不缓存（确保每次请求都获取最新）
    location = /index.html {
        expires -1;
        add_header Cache-Control "no-cache, no-store, must-revalidate";
    }

    # 其他静态文件（favicon, robots.txt）
    location ~* \.(ico|webmanifest)$ {
        expires 30d;
        add_header Cache-Control "public";
        access_log off;
    }

    # ===== 安全头部 =====
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # ===== 日志 =====
    access_log /var/log/nginx/access.log main buffer=32k flush=5s;
    error_log /var/log/nginx/error.log warn;
}

缓存策略对比

踩坑点

五、部署方案对比

5.1 四种主流方案

前端部署方案的选择取决于项目规模、团队能力和基础设施。

5.2 静态资源 CDN 部署（OSS + CDN）

# ---------- GitHub Actions：OSS + CDN 部署 ----------
name: Deploy to OSS + CDN

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm run build:prod

      # 上传到 OSS
      - name: Upload to OSS
        uses: aliyun/oss-upload-action@v1
        with:
          access-key-id: ${{ secrets.OSS_ACCESS_KEY_ID }}
          access-key-secret: ${{ secrets.OSS_ACCESS_KEY_SECRET }}
          bucket: my-app-static
          source: ./dist/
          target: /web-app/

      # CDN 刷新（确保缓存立即失效）
      - name: Refresh CDN Cache
        run: |
          aliyun cdn RefreshObjectCaches \
            --ObjectPath https://cdn.example.com/web-app/index.html \
            --ObjectType File

部署结构

OSS Bucket: my-app-static
└── web-app/
    ├── v1.0.0/                    # 版本号目录
    │   ├── index.html
    │   └── assets/
    │       ├── index.abc123.js
    │       └── styles.def456.css
    ├── v1.1.0/
    │   └── ...
    ├── current -> v1.1.0/         # 符号链接指向当前版本
    └── rollback -> v1.0.0/        # 回滚版本

5.3 Nginx 服务器部署

# ---------- 手动部署 / CI 中的部署脚本 ----------
#!/bin/bash
set -euo pipefail

APP_NAME="my-frontend"
DEPLOY_DIR="/data/apps/${APP_NAME}"
VERSION=$(date +%Y%m%d%H%M%S)

# 1. 创建版本目录
mkdir -p "${DEPLOY_DIR}/releases/${VERSION}"

# 2. 复制构建产物
cp -r ./dist/* "${DEPLOY_DIR}/releases/${VERSION}/"

# 3. 更新软链接
ln -snf "${DEPLOY_DIR}/releases/${VERSION}" "${DEPLOY_DIR}/current"

# 4. 清理旧版本（保留最近 5 个版本）
ls -t "${DEPLOY_DIR}/releases/" | tail -n +6 | xargs -I {} rm -rf "${DEPLOY_DIR}/releases/{}"

echo "Deployed: ${VERSION}"

# ---------- Nginx 多版本部署配置 ----------
server {
    root /data/apps/my-frontend/current;
    # 使用符号链接实现零停机部署
    # 更新软链接后 reload 即可
}

5.4 Docker + K8s 部署

# ---------- Kubernetes Deployment ----------
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  namespace: production
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1        # 最大不可用 Pod 数
      maxSurge: 1              # 最大额外 Pod 数
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
        - name: frontend
          image: registry.example.com/frontend:1.2.3
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi
          livenessProbe:
            httpGet:
              path: /health
              port: 80
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /index.html
              port: 80
            initialDelaySeconds: 3
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: frontend-svc
spec:
  selector:
    app: frontend
  ports:
    - port: 80
      targetPort: 80
  type: ClusterIP

# ---------- K8s 滚动更新回滚命令 ----------
# 部署
kubectl set image deployment/frontend frontend=registry.example.com/frontend:1.2.4

# 查看状态
kubectl rollout status deployment/frontend

# 回滚到上一个版本
kubectl rollout undo deployment/frontend

# 回滚到指定版本
kubectl rollout undo deployment/frontend --to-revision=3

# 查看版本历史
kubectl rollout history deployment/frontend

5.5 Vercel / Netlify 部署

# ---------- Vercel 部署（vercel.json）----------
{
  "buildCommand": "npm run build:prod",
  "outputDirectory": "dist",
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ],
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, immutable, max-age=31536000" }
      ]
    }
  ]
}

# ---------- Netlify 部署（netlify.toml）----------
[build]
  command = "npm run build:prod"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, immutable, max-age=31536000"

踩坑点

六、灰度发布

6.1 Nginx 流量分流

权重分流

# ---------- Nginx 权重分流 ----------
upstream frontend {
    # 稳定版（90% 流量）
    server 10.0.1.10:80 weight=9;
    # 灰度版（10% 流量）
    server 10.0.1.11:80 weight=1;
}

server {
    location / {
        proxy_pass http://frontend;
    }
}

Header / Cookie 分流

# ---------- Nginx Header/Cookie 灰度分流 ----------
upstream frontend-stable {
    server 10.0.1.10:80;
}

upstream frontend-canary {
    server 10.0.1.11:80;
}

server {
    location / {
        # 根据 Cookie 分流
        if ($http_cookie ~* "canary=1") {
            proxy_pass http://frontend-canary;
            break;
        }

        # 根据 Header 分流
        if ($http_x_canary) {
            proxy_pass http://frontend-canary;
            break;
        }

        # 默认走稳定版
        proxy_pass http://frontend-stable;
    }
}

6.2 K8s 灰度发布

# ---------- K8s Canary 部署 ----------
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend-canary
  labels:
    app: frontend
    track: canary
spec:
  replicas: 1                    # 灰度实例数
  selector:
    matchLabels:
      app: frontend
      track: canary
  template:
    metadata:
      labels:
        app: frontend
        track: canary
    spec:
      containers:
        - name: frontend
          image: registry.example.com/frontend:1.3.0-beta
---
# Service 通过 label selector 同时覆盖 stable 和 canary
apiVersion: v1
kind: Service
metadata:
  name: frontend-svc
spec:
  selector:
    app: frontend
  ports:
    - port: 80

# 通过调整 canary 的 replicas 控制灰度比例
# stable: 9 个 Pod, canary: 1 个 Pod → canary 10% 流量
# stable: 8 个 Pod, canary: 2 个 Pod → canary 20% 流量

6.3 灰度发布策略对比

6.4 AB 实验平台

// ---------- AB 实验 SDK 封装 ----------
// src/utils/experiment.ts
// 防御：实验分组信息不可信，需验证

interface ExperimentConfig {
  /** 实验名称 */
  name: string
  /** 实验分组 */
  variants: string[]
  /** 流量分配比例（总和 = 1） */
  weights: number[]
}

class ABExperiment {
  private experiments: Map<string, string>

  constructor() {
    this.experiments = new Map()
  }

  /**
   * 从服务端获取实验分组
   */
  async init(userId: string): Promise<void> {
    try {
      const res = await fetch('/api/experiments/assign', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ userId }),
      })
      const data = await res.json()

      // 防御：验证返回数据格式
      if (data?.experiments && typeof data.experiments === 'object') {
        Object.entries(data.experiments).forEach(([key, value]) => {
          if (typeof value === 'string') {
            this.experiments.set(key, value)
          }
        })
      }
    } catch {
      // 防御：实验平台不可用，走默认分组
      console.warn('AB 实验平台不可用，使用默认分组')
    }
  }

  /**
   * 获取当前用户的实验分组
   */
  getVariant(experimentName: string, defaultValue = 'control'): string {
    // 防御：返回默认值而不是抛错
    return this.experiments.get(experimentName) ?? defaultValue
  }

  /**
   * 判断用户是否在指定实验的实验组
   */
  isInGroup(experimentName: string, variant: string): boolean {
    return this.getVariant(experimentName) === variant
  }
}

export const experiment = new ABExperiment()

// ---------- Vue 3：AB 实验使用 ----------
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { experiment } from '@/utils/experiment'

const showNewHomePage = ref(false)
const showBanner = ref(false)

onMounted(async () => {
  await experiment.init(getCurrentUserId())

  // 实验 A：新版首页 vs 旧版首页
  showNewHomePage.value = experiment.isInGroup('homepage-redesign', 'treatment')

  // 实验 B：横幅展示
  showBanner.value = experiment.isInGroup('promo-banner', 'treatment')
})
</script>

<template>
  <!-- 根据实验分组渲染不同版本 -->
  <NewHomePage v-if="showNewHomePage" />
  <OldHomePage v-else />
</template>

// ---------- React：AB 实验 Hook ----------
// src/hooks/useExperiment.ts
import { useState, useEffect } from 'react'
import { experiment } from '@/utils/experiment'

export function useExperiment(experimentName: string, defaultValue = 'control') {
  const [variant, setVariant] = useState(defaultValue)
  const [loaded, setLoaded] = useState(false)

  useEffect(() => {
    experiment.init(getCurrentUserId()).then(() => {
      setVariant(experiment.getVariant(experimentName, defaultValue))
      setLoaded(true)
    })
  }, [experimentName, defaultValue])

  return {
    variant,
    loaded,
    isTreatment: variant === 'treatment',
  }
}

// ---------- 使用 ----------
function HomePage() {
  const { variant, loaded, isTreatment } = useExperiment('homepage-redesign')

  if (!loaded) return <Skeleton />  // 防御：实验未加载完成前显示骨架屏

  return isTreatment ? <NewHomePage /> : <OldHomePage />
}

七、前端发布注意事项

7.1 非覆盖式发布

核心原则：永远不要覆盖已发布的静态资源文件。这是前端发布最底层的原则。

# ❌ 覆盖式发布（危险）
# 每次构建都生成相同文件名
dist/assets/index.js    # 被覆盖，CDN 缓存未更新
dist/assets/styles.css  # 被覆盖

# ✅ 非覆盖式发布（安全）
dist/v1.0.0/assets/index.a1b2c3d4.js
dist/v1.0.0/assets/styles.e5f6g7h8.css
dist/v1.0.1/assets/index.i9j0k1l2.js
dist/v1.0.1/assets/styles.m3n4o5p6.css

为什么必须非覆盖式发布

7.2 缓存更新策略

# ---------- Nginx 多级缓存控制 ----------
# HTML：禁止缓存
location = /index.html {
    add_header Cache-Control "no-store, no-cache, must-revalidate";
    add_header Pragma "no-cache";
    expires -1;
}

# 带 Hash 的资源：永久缓存
location /assets/ {
    # 文件名包含 Hash，内容变则文件名变
    expires 1y;
    add_header Cache-Control "public, immutable";
}

// ---------- Service Worker 策略 ----------
// 对于 PWA 项目，使用 Service Worker 精细控制缓存

// sw.ts
const CACHE_NAME = 'app-v1'

// 安装时预缓存核心资源
self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open(CACHE_NAME).then((cache) => {
      return cache.addAll([
        '/index.html',
        '/assets/vendor.a1b2c3d4.js',
        '/assets/app.e5f6g7h8.js',
      ])
    }),
  )
})

// 激活时清理旧缓存
self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((cacheNames) => {
      return Promise.all(
        cacheNames
          .filter((name) => name !== CACHE_NAME)
          .map((name) => caches.delete(name)),
      )
    }),
  )
})

踩坑点

7.3 回滚方案

# ---------- Nginx 回滚脚本 ----------
#!/bin/bash
set -euo pipefail

APP_NAME="my-frontend"
DEPLOY_DIR="/data/apps/${APP_NAME}"
TARGET_VERSION="${1:-}"

if [ -z "$TARGET_VERSION" ]; then
    # 默认回滚到上一个版本
    CURRENT=$(readlink "${DEPLOY_DIR}/current")
    PREVIOUS=$(ls -t "${DEPLOY_DIR}/releases/" | sed -n '2p')
    TARGET_VERSION="$PREVIOUS"
fi

# 安全：检查版本目录是否存在
if [ ! -d "${DEPLOY_DIR}/releases/${TARGET_VERSION}" ]; then
    echo "错误：版本 ${TARGET_VERSION} 不存在"
    exit 1
fi

# 执行回滚
ln -snf "${DEPLOY_DIR}/releases/${TARGET_VERSION}" "${DEPLOY_DIR}/current"
nginx -s reload

echo "回滚到版本 ${TARGET_VERSION} 完成"

八、CI 工具配置示例

8.1 GitHub Actions 完整示例

# ---------- .github/workflows/ci-cd.yml ----------
name: CI/CD Pipeline

on:
  push:
    branches: [main, 'release/*']
  pull_request:
    branches: [main]

# 环境变量
env:
  NODE_VERSION: 20
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  # ===== 代码质量检查 =====
  lint:
    name: Code Quality
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - run: npm ci
      - run: npx tsc --noEmit
      - run: npx eslint . --max-warnings 0
      - run: npx prettier --check .

  # ===== 单元测试 =====
  test:
    name: Unit Tests
    needs: [lint]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - run: npm ci
      - name: Run Tests with Coverage
        run: npx vitest run --coverage

      - name: Upload Coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

  # ===== E2E 测试 =====
  e2e:
    name: E2E Tests
    needs: [test]
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - run: npm ci
      - run: npm run build
      - run: npx playwright install chromium

      - name: Run E2E Tests
        run: npx playwright test

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/

  # ===== 构建与发布 =====
  build-and-deploy:
    name: Build & Deploy
    # PR 不部署，只有合并到 main 才部署
    if: github.ref == 'refs/heads/main'
    needs: [e2e]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'

      - run: npm ci
      - name: Build
        run: npm run build:prod

      # 构建 Docker 镜像
      - name: Log in to Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and Push Docker Image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}

      # 部署通知
      - name: Notify Deployment
        if: always()
        run: |
          STATUS="${{ job.status }}"
          MESSAGE="前端部署 $([ "$STATUS" = "success" ] && echo '成功' || echo '失败')"
          curl -X POST -H "Content-Type: application/json" \
            -d "{\"msgtype\":\"text\",\"text\":{\"content\":\"${MESSAGE}\"}}" \
            ${{ secrets.WEBHOOK_URL }}

8.2 GitLab CI 完整示例

# ---------- .gitlab-ci.yml ----------
stages:
  - lint
  - test
  - build
  - deploy

variables:
  NODE_VERSION: "20"
  NPM_CACHE: "npm-cache"

# 缓存 node_modules
cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - node_modules/

# ===== 代码质量 =====
lint:
  stage: lint
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npx tsc --noEmit
    - npx eslint . --max-warnings 0
    - npx prettier --check .

# ===== 单元测试 =====
unit-test:
  stage: test
  image: node:${NODE_VERSION}
  script:
    - npm ci
    - npx vitest run --coverage
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml

# ===== E2E 测试 =====
e2e-test:
  stage: test
  image: mcr.microsoft.com/playwright:v1.45.0-focal
  script:
    - npm ci
    - npx playwright install chromium
    - npm run build
    - npx playwright test
  artifacts:
    when: always
    paths:
      - playwright-report/
    expire_in: 7 days

# ===== 构建 =====
build:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA $CI_REGISTRY_IMAGE:latest
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest
  only:
    - main

# ===== 部署到开发环境 =====
deploy-dev:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client
  script:
    - scp -r ./dist/* deploy@dev-server:/data/apps/frontend/
  environment:
    name: development
  only:
    - main

# ===== 部署到生产环境 =====
deploy-production:
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl set image deployment/frontend frontend=$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - kubectl rollout status deployment/frontend
  environment:
    name: production
  when: manual          # 手动触发部署
  only:
    - main

8.3 CI 工具对比

踩坑点

参考资料

• GitHub Actions 官方文档
• GitLab CI 官方文档
• Playwright CI 配置指南
• Vite 多环境配置
• Docker 多阶段构建最佳实践
• Nginx 前端部署最佳实践
• Chromatic 文档
• Kubectl 部署与回滚

最后更新：2026/06/29