小时候的发版流程是这样的:负责人本地 npm run build,用 QQ 传一个压缩包给运维,运维解压到服务器,手动改一下配置文件里的接口地址,刷新页面,出问题再回滚。每次发版半小时,周五下午发版尤其刺激。

有一次,负责人在自己的 .env.local 里把接口指向了测试环境,本地构建时被打进了产物。测试环境一切正常,上线后所有请求打到测试库,用户看到的是三个月前的数据。排查了两个小时,最后发现是「换台机器构建,结果就不一样」。

这篇讲什么:CI 和 CD 各自负责什么、一条流水线应该按什么顺序跑、为什么必须「构建一次、多环境部署」、部署怎么做成可回滚的原子操作、密钥和权限怎么管。读完你能做到:把一条手工发版流程改成可重复的流水线;遇到「CI 绿了但部署挂了」能按阶段定位;知道回滚到底该回什么。

版本说明:示例用 GitHub Actions,命令和结构在其他 CI 平台(GitLab CI、Jenkins)里思路一致。Action 的版本号按写这篇时的主流版本给,具体以你仓库当前的官方推荐为准。

CI 和 CD,不是一回事

CI(持续集成)解决的是「代码合进来能不能用」:每次推送或 PR,自动装依赖、跑检查、跑测试、构建,尽早发现冲突和回归。它的产出是一个「验证结果」和一个「可部署的产物」。

CD 有兩種常見含義,這裡要分清:Continuous Delivery(持续交付)是「随时可以发布」,最后一脚由人点;Continuous Deployment(持续部署)是「通过检查就自动上线」。多数团队适合持续交付,生产发布保留一次人工确认,尤其是涉及钱和数据的系统。

两者共同的底座是「可重复」。同一份代码、同一个命令、同一个环境,每次得到同样的产物。手工发版最大的问题不是慢,而是不可重复:换个人、换台机器、忘了改一个变量,结果就不同。

一条流水线该有的顺序

流水线的设计原则是「便宜的先跑,贵的后跑,失败早退出」。装依赖最便宜,构建和端到端最贵。顺序错了,等十分钟才告诉你少个分号,没人愿意用。

一条典型的前端流水线
安装依赖锁定版本,命中缓存
静态检查Lint、类型检查,可并行
测试与构建单测、组件测试,产出制品
部署与验证上传、切换、冒烟检查

几个具体建议:

  • Lint、类型检查、单测可以并行跑,别串成一条线等三轮。
  • 构建只做一次,产物上传成 artifact;部署阶段只下载和搬运,不再重新构建。
  • PR 阶段不部署生产,最多部署一个临时预览环境;合并到主分支才进入发布链路。
  • 同一个分支连续推送时,取消上一次还在跑的流水线,省时间也省 CI 额度。
  • 部署后必须有一次冒烟检查,确认页面能打开、关键接口能通、版本号对得上。

缓存:流水线速度的大头

前端流水线最容易被「装依赖」拖慢。缓存做对了,安装从几分钟降到几十秒;做错了,缓存天天失效,比不缓存还慢。

正确的缓存键是「锁文件的哈希」。锁文件不变,依赖就不变,缓存可以复用;锁文件一变,缓存自动失效,不会装出旧版本。不要缓存整个 node_modules,它体积大、跨平台容易出问题;缓存包管理器的全局仓库(npm 的 cache、pnpm 的 store)更稳。

- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm

- run: pnpm install --frozen-lockfile

构建缓存是另一回事。有的工具支持把上一次的构建结果缓存下来,只重建改动的部分;前端项目里收益不如依赖缓存稳定,先别急着上。端到端测试的浏览器二进制也可以缓存,但要注意版本和缓存键绑定。

来自 fork 的 PR 不要复用主分支的缓存,也不要给它注入密钥。缓存可以被写入,恶意 PR 可能污染缓存内容。多数平台的缓存默认按分支隔离,但配置时要确认这一点。

构建一次,多环境部署

这一条是流水线里最容易被违反、后果也最严重的原则。很多团队的做法是:测试环境构建一次,生产环境再构建一次,只是换了个环境变量。看起来没问题,实际上「测试过的产物」和「上线的产物」不是同一个文件。

构建过程不是完全确定的。依赖解析、构建工具版本、环境变量、甚至文件遍历顺序,都可能让两次构建产生不同的哈希和不同的代码。你在测试环境验证的是 A 产物,上线的是 B 产物,B 里恰好带了一个只在生产模式才启用的分支,问题就漏过去了。

正确做法是:构建一次,产出带版本标识的 artifact,测试、预发、生产都部署同一个 artifact。环境差异通过「运行期配置」注入,而不是重新构建。静态站点可以把环境配置写成一个启动时生成的 config.json,或者由 nginx 在返回 HTML 时替换占位符;前端应用启动时先拉这个配置,再初始化。具体方案在下一篇展开。

产物要能追溯。每次构建写一个 version.json,里面至少包含提交 SHA、构建时间、构建号:

{
  "sha": "9f3c2a1",
  "builtAt": "2026-11-06T10:12:00Z",
  "version": "1.8.0"
}

部署后用这个文件做冒烟检查,确认线上跑的确实是这次构建的产物,而不是缓存里的旧版本。

原子发布:要么全旧,要么全新

直接往线上目录里覆盖文件,是最危险的部署方式。上传到一半失败,用户会拿到「一半新、一半旧」的页面:新 HTML 引用了还没传上去的 JS,直接白屏。

静态资源常用「版本目录加软链接」的做法:每次发布上传到一个独立目录,传完再原子地切换 current 指向它。

原子发布与回滚
上传新版本写入 releases/提交号目录
校验完整性文件数量、版本文件、关键页面
切换软链接current 指向新目录,瞬间生效
保留旧版本回滚只需把链接指回去
/srv/app/releases/9f3c2a1/
/srv/app/releases/8b1d4e0/
/srv/app/current -> /srv/app/releases/9f3c2a1

回滚就是把 current 指回上一个目录,通常几十秒内完成,不用重新构建,也不用等 CI。保留最近五个版本,既够回滚,也不至于把磁盘塞满。清理旧版本放在发布成功后做,别在发布前删,否则回滚时找不到东西。

缓存是原子发布的一部分。带哈希的资源可以长缓存,HTML 必须短缓存或不缓存;发布后如果前面有 CDN,还要记得刷新 HTML 和版本文件。否则源站已经切到新版本,用户拿到的还是旧页面,继续请求已经删掉的旧资源。

如果发布涉及数据库变更,回滚就不只是切目录了。前端能瞬间回退,数据库结构不能。稳妥的做法是「扩展与收缩」:先加新字段、兼容新旧代码,等所有实例都升级完,再删旧字段。任何一次发布里都不要做「不可逆」的结构变更,这条规则和回滚能力直接相关。

密钥与权限:别让流水线成为后门

流水线要部署,就得有服务器密钥、registry token、通知 webhook。这些东西一旦泄露,影响比一个前端 bug 大得多。几条底线:

  • 密钥放在平台的 secrets 里,不写进仓库、不写进构建命令、不打印到日志。
  • 部署密钥只给部署需要的权限,能写一个目录就不要给整台机器的 root。
  • 生产部署配置「需要人工批准」的环境保护,别让任何一次推送自动上生产。
  • 来自 fork 的 PR 默认拿不到 secrets;不要把 pull_request_target 和检出 PR 代码、执行脚本组合使用,那是典型的提权路径。
  • 工作流显式声明最小权限,比如只需要读代码就写 permissions: contents: read。

SSH 部署还要处理 known_hosts。第一次连接时用 ssh-keyscan 写入主机指纹,或者提前把指纹固定在 secrets 里;不要用「跳过主机校验」的选项,那等于对中间人攻击不设防。

密钥要能轮换。部署密钥、registry token 都设过期时间,离职或泄漏时立刻换。流水线里写死一个永不过期的 token,短期省事,长期是隐患。

一份能跑的 GitHub Actions 配置

下面这份配置把「验证」和「部署」拆成两个 job,验证阶段产出 artifact,部署阶段只搬运,不重新构建。

name: build-and-deploy

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 10
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm typecheck
      - run: pnpm test -- --run
      - run: pnpm build
      - name: 写入版本文件
        run: echo "{\"sha\":\"$GITHUB_SHA\"}" > dist/version.json
      - uses: actions/upload-artifact@v4
        with:
          name: dist-${{ github.sha }}
          path: dist
          retention-days: 14

  deploy:
    needs: verify
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist-${{ github.sha }}
          path: dist
      - name: 配置 SSH
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SSH_KEY }}" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan -H "${{ secrets.SSH_HOST }}" >> ~/.ssh/known_hosts
      - name: 上传新版本
        run: |
          ssh "${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}" \
            "mkdir -p /srv/app/releases/${{ github.sha }}"
          rsync -az dist/ \
            "${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}:/srv/app/releases/${{ github.sha }}/"
      - name: 切换并重载
        run: |
          ssh "${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}" \
            "ln -sfn /srv/app/releases/${{ github.sha }} /srv/app/current"
          ssh "${{ secrets.SSH_USER }}@${{ secrets.SSH_HOST }}" \
            "sudo systemctl reload nginx"
      - name: 冒烟检查
        run: |
          curl -fsS https://app.example.com/version.json \
            | grep -q "$GITHUB_SHA"

几个容易忽略的细节。第一,concurrency 保证同一分支不会有两个部署同时跑,后一个会取消前一个。第二,environment: production 触发环境保护规则,可以在平台里配置必须人工批准。第三,冒烟检查用 curl -f,HTTP 非 2xx 会直接失败,不要只看命令有没有报错。第四,sudo systemctl reload nginx 需要运维提前配好免密 sudo 的最小权限,别为了省事给全权限。

如果站点是纯静态、没有 nginx 重载需求,最后一步可以去掉,只保留软链接切换和冒烟。Action 的版本号按仓库当前推荐来,@v4 是写这篇时的主流,升级到 v5 通常只是改版本号,但要注意运行时环境变化。

完整场景走查:从十八分钟到六分钟

背景是一个内部后台,原来发版靠负责人本地构建、scp 上传、手动改配置,平均二十分钟,出问题靠回忆上一次改了什么。迁移到流水线分三步走。

第一步,先把验证自动化,不碰部署。每周一上班第一件事是跑一遍 Lint、类型检查、单测和构建,记录每一步耗时。第一次串行跑完十八分钟,其中安装依赖六分钟、端到端八分钟、构建两分钟。只做缓存和并行,就降到九分钟。

第二步,把部署改成「构建一次、上传版本目录、软链接切换」。生产发布保留人工批准,批准后三分钟内完成。第一次演练回滚,从发现问题到切回上一版本用了四十秒,比重新构建快得多。

第三步,加冒烟和版本追踪。部署后先请求 version.json 比对 SHA,再请求首页和关键接口。上线第一个月真拦下过一次:部署成功,但 CDN 缓存了旧 HTML,version.json 是新的,首页里的资源还是旧路径,用户白屏。第一版冒烟只查了版本文件,没查首页资源,漏了。后来把检查改成「抓取首页 HTML,提取主 JS 地址,再请求这个地址确认返回 200」,才补上。

最终流水线:安装四十秒(缓存命中)、Lint 二十五秒、类型检查五十秒、单测七十秒、构建一百秒,前三项并行,验证阶段约三分钟;部署与冒烟两分半,合计六分钟左右。发布频率从两周一次变成一周两次,回滚演练从「不敢做」变成「每季度一次」。

几个数字值得记住:安装依赖从六分钟降到四十秒,靠的是缓存键按锁文件哈希;端到端从八分钟降到三分钟,靠的是分片和登录态复用;部署从二十分钟降到三分钟,靠的是「传完再切」。每一步都能单独度量,出了问题也知道哪一段慢。

错误现象对照

现象真实原因第一步查什么
CI 全绿,线上资源 404部署路径和构建时的 base 不一致请求首页,看 HTML 里的资源地址和实际部署目录
同一提交在测试和生产表现不同每个环境重新构建,产物不是同一个对比两边的 version.json 和构建产物哈希
--frozen-lockfile 只有 CI 失败改了依赖没提交锁文件本地安装后看锁文件是否进入提交
部署 job 连不上服务器密钥、主机指纹、防火墙或用户权限用同一个密钥手动连一次,看失败在哪一步
回滚后仍然报错旧版本目录被清理,或数据库已做了不可逆变更检查 releases 保留策略和迁移脚本
冒烟通过,用户仍看到旧页面CDN 或浏览器缓存了旧 HTML看响应头里的缓存策略,刷新 CDN 再验证
流水线一次二十分钟步骤串行、没缓存、端到端过多看各阶段耗时,先并行静态检查,再加缓存
密钥出现在日志里命令里 echo 了敏感变量删除日志、立即轮换密钥、检查同类命令

边界与代价

流水线本身是要维护的代码。环境镜像升级、Action 版本变化、依赖缓存失效、密钥过期,都会让它某天突然红。团队要有人负责这块,不能「配好就不管」。一个没人维护的流水线,半年后会变成所有人绕过的障碍。

小项目不必上全套。一个纯静态文档站,一条「构建、上传、冒烟」的流水线就够了,不需要分片、不需要多环境、不需要审批。流水线的复杂度应该和发布风险匹配,不是和团队的技术热情匹配。

人工审批也有代价。每次发布都等人点,会把发布频率压下来,大家倾向于攒大版本,一次上更多东西,风险反而更高。审批应该留给高风险环境,测试和预发自动发布;生产可以要求批准,但要把批准时间控制在几分钟,而不是半天。

自建 runner 能省钱、能访问内网,但要自己负责安全更新、磁盘清理和隔离。公开仓库不要用自建 runner 跑来自 fork 的代码,那是把内网暴露给陌生人。用托管 runner 时,注意免费额度,端到端跑得多会烧得很快。

最后一条:自动化不会修复一个本来就乱的流程。发布前要手工改五个配置、数据库迁移靠人记、回滚靠运气,这些问题不会因为加了 YAML 就消失,只会变得更快、更频繁。先把「构建一次」「可回滚」「配置外置」这三件事理顺,再谈流水线。

小结

CI 管验证,CD 管交付PR 阶段跑检查,主分支产出制品;持续交付保留人工批准,持续部署才全自动。
便宜的先跑,失败早退出安装、Lint、类型检查在前,测试与构建在后;能并行的并行,同分支取消旧任务。
构建一次,多环境部署环境差异用运行期配置注入;产物带 SHA,部署后用它做冒烟。
发布要原子,回滚要演练版本目录加软链接,保留最近几个版本;不可逆的数据库变更不要和发布放在一起。
密钥最小权限secrets 不落日志,生产要审批,fork 的 PR 不给密钥,定期轮换。

当天可以动手的练习:

  1. 在本地按顺序跑一遍安装、Lint、类型检查、单测、构建,记录每一步耗时。
  2. 给一个小项目加 CI,只跑 Lint、类型检查和单测,先不碰部署。
  3. 构建一次,把产物下载到另一个目录部署,对比两边的 version.json,确认是同一份。
  4. 在本机用两个目录加一个软链接模拟发布和回滚,记录切换耗时。
  5. 写一个冒烟脚本,检查版本文件和首页主资源的 HTTP 状态。

下一篇讲环境变量、配置与多环境部署。流水线里反复提到「环境差异用运行期配置注入」,这一篇就把这件事拆开:哪些配置该在构建时写死,哪些必须留到运行时,密钥为什么绝对不能进前端产物,以及多环境怎么不靠复制粘贴维护。