前端 CI/CD 部署

前端 CI/CD 部署的核心结论只有一句话：让构建产物可复现、让发布可回滚。一条完整流水线固定跑五步——装依赖、跑 lint 与测试、构建、上传静态产物、刷新 CDN 或切换流量；任何一步失败就停在原地，生产环境永远只发布「带 hash 的静态资源 + 一份不缓存的 index.html」。

前端 CI/CD 包含哪几个阶段？

结论：前端 CI/CD 分 CI（持续集成）和 CD（持续交付/部署）两段，CI 负责「代码到产物」，CD 负责「产物到用户」。

CI 阶段三件事必须做全：npm ci 精确安装依赖（按 package-lock.json 还原，本地和流水线结果一致）、eslint 与 tsc --noEmit 做静态检查、vitest run 或 jest --ci 跑单测。这三步都绿了才允许 npm run build。

CD 阶段是「上传 + 生效」：把 dist/ 目录传到对象存储或服务器，再刷新 CDN 缓存。判断标准很简单——构建产物是纯静态文件，就不需要重启服务，发布动作只是替换文件加上刷缓存。

GitHub Actions 的部署配置怎么写？

结论：一份最小可用的 workflow 只需要 4 个 action，写在一个 job 里 30 行以内能跑完。

name: deploy
on:
  push:
    branches: [main]
jobs:
  build-deploy:
    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
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist

actions/setup-node@v4 的 cache: npm 会自动缓存 npm 全局目录，key 基于 package-lock.json 的哈希，锁文件不变就命中缓存。最后一步换成 aws s3 sync dist/ s3://your-bucket --delete 或 rsync 到服务器即可完成上传。

前端构建缓存怎么做才能真的快？

结论：依赖缓存和构建缓存要分开做，依赖缓存命中后安装阶段能从 40 秒降到 3 秒以内。

依赖缓存交给 setup-node 的 cache 参数就够了。构建缓存需要用 actions/cache@v4 单独缓存 node_modules/.vite（Vite）或 node_modules/.cache（Webpack），key 里带上源码哈希：

- uses: actions/cache@v4
  with:
    path: node_modules/.vite
    key: vite-${{ hashFiles('package-lock.json') }}-${{ hashFiles('src/**') }}

注意点：缓存 key 必须包含锁文件哈希，否则依赖升级后仍复用旧缓存，会出现「本地正常、线上白屏」的依赖错配。一个 3000 模块量级的 Vite 项目冷构建在 GitHub 托管 runner 上通常 20-40 秒，命中依赖缓存后可压到 10 秒以内。

前端部署上线怎么保证用户不白屏？

结论：靠文件名 hash 加分级缓存策略，把「缓存过期」问题从根上消掉。

构建工具产出的 index.[hash].js、index.[hash].css 内容变了文件名就变，可以放心设长缓存；index.html 引用的文件名会变，所以它自己绝不能长缓存。Nginx 配置参考：

location = /index.html {
  add_header Cache-Control "no-cache";
}
location ~* \.(js|css|png|woff2)$ {
  add_header Cache-Control "public, max-age=31536000, immutable";
}

max-age=31536000 是 1 年，配合 immutable 让浏览器不再发条件请求。发布顺序也要注意：先上传新的 hash 文件，最后再覆盖 index.html，这样在切换的几秒内老页面引用的旧文件依然存在，不会 404。

回滚方案同理：每次发布产物存到独立目录，如 releases/20240612-1530/，用软链接 current 指向当前版本。回滚只需把软链接重指到上一个版本，1 条命令、10 秒内完成，不需要重新构建。

前端 CI/CD 常见的坑有哪些？

结论：80% 的线上事故来自三个地方——环境变量没分环境、Source Map 没上传、构建用了开发依赖。

环境变量必须在 CI 里按分支注入，.env.production 不要提交到仓库；在 workflow 里用 env: 或 GitHub Secrets 传入，构建时通过 import.meta.env.VITE_API_BASE 读取，注意 Vite 只暴露 VITE_ 前缀的变量。

Source Map 要单独上传到错误监控平台（如 Sentry），并在构建时设 build.sourcemap: 'hidden'，产物里不带 map 引用但文件生成了，方便线上定位又不会泄露源码。

最后确认 npm ci --omit=dev 与 npm ci 的区别：构建阶段需要 devDependencies（Vite、TypeScript 都在里面），只有纯运行时的 Node 服务才用 --omit=dev。把这两者搞混，是「本地能构建、CI 报找不到 vite」的最常见原因。

一句话收束：前端 CI/CD 不是把命令堆进脚本，而是把「构建可复现、产物可寻址、发布可回滚」这三件事固定成流程，剩下的都是配置细节。