CI/CD 流水线本地能跑但构建失败怎么排查？

Question

仓乃文 · Accepted Answer

"本地没问题，CI 挂了"是最让人崩溃的工程化问题。90% 的原因是环境不一致：Node 版本、依赖版本、环境变量、文件大小写。

常见原因与修复：
```bash
# 原因 1：Node 版本不一致
# 修复：在 CI 配置中明确指定 Node 版本
# GitHub Actions
- uses: actions/setup-node@v3
  with:
    node-version: "20"
# 或创建 .nvmrc
echo "20" > .nvmrc

# 原因 2：依赖版本不一致
# 修复：CI 中用 npm ci 而不是 npm install
- run: npm ci  # 不是 npm install！

# 原因 3：环境变量缺失
# 修复：在 CI 配置中注入环境变量
- run: npm run build
  env:
    VITE_API_URL: ${{ secrets.API_URL }}

# 原因 4：文件大小写问题
# macOS 不区分大小写，Linux 区分
# import Header from "./header" 但文件名是 Header.tsx
# 修复：确保 import 路径和文件名大小写完全一致

# 原因 5：测试依赖外部服务
# 修复：用 Docker Service 或 Mock
services:
  postgres:
    image: postgres:15
```

排查流程：
```bash
# 1. 用 Docker 模拟 CI 环境
docker run -it --rm -v $(pwd):/app -w /app node:20-alpine sh
npm ci && npm run build && npm test

# 2. 对比环境差异
echo "Node: $(node -v)" && echo "npm: $(npm -v)" && echo "OS: $(uname -a)"

# 3. 检查 lockfile 是否提交
git ls-files | grep lock
# package-lock.json 或 pnpm-lock.yaml 必须提交！
```

CI 配置最佳实践：
```yaml
name: CI
on: [push, pull_request]
jobs:
  build:
    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 lint
      - run: npm run typecheck
      - run: npm run build
      - run: npm test
```

补充说明：
- 规则：CI 中用 npm ci，不用 npm install
- lockfile 必须提交到仓库
- 文件大小写是 macOS 开发者的隐形杀手
- 用 Docker 模拟 CI 环境是最快的排查方式
- 环境变量通过 CI 的 secrets 管理，不要写在代码里