DevOps CI/CD 流水线搭建完整指南

小团队引入流水线，最该解决的不是"有没有 CI"，而是每次提交能不能在十分钟内得到一个可信的结论。这篇讲我们给客户搭基线流水线时的阶段划分、判断标准，以及踩过的几个坑。

三条设计原则

一、反馈要快。Lint 与单元测试控制在 5 分钟内，整条流水线不超过 10 分钟。超过这个尺度，开发者会切换去做别的事，等结果回来时上下文已经丢了——最常见的后果是"顺手改点别的一起提交"，一次提交混进多个改动。

二、门禁要渐进。顺序固定为：格式与类型检查 → 单元测试 → 构建 → 集成测试 → 部署。任何一步失败立刻停，后面的不用跑，既省资源也让人最快看到失败原因。

三、结果要可重复。同一份代码，今天跑和下周跑结果必须一致。做法是用容器固定构建环境、锁死依赖版本（pnpm-lock.yaml 这类锁文件要进版本库、CI 用 --frozen-lockfile 安装）。

六个阶段的划分

1. 静态检查（1～2 分钟）：ESLint + 格式化检查 + TypeScript 类型检查。这一阶段最好在本地 pre-commit 就拦掉，CI 只作兜底。

2. 单元测试（3～5 分钟）：跑测试并检查覆盖率阈值。测试多了以后用分片（sharding）拆到多个 job 并行，别让它成为整条流水线最慢的一环。

3. 构建（2～4 分钟）：产出生产构建物，并作为不可变产物（artifact）传给后面的阶段——后续阶段复用同一份产物，避免"测的和发的不是同一个东西"。

4. 集成与端到端测试：用容器化的数据库、缓存把依赖拉起来跑端到端用例。这一阶段最容易不稳定，见下面第二、三个坑。

5. 部署到预发：自动部署，跑一轮核心流程冒烟（登录、下单、支付这类主链路），再决定是否放行。

6. 部署生产：审批后发布，优先用滚动或灰度；发布后自动比对关键指标（错误率、接口耗时），异常自动回滚。

我们踩过的四个坑

1. 不稳定的测试混在门禁里。一个偶发失败的用例会让整条流水线变成"重跑一次就好"，很快所有人都不再相信 CI。做法是给这类用例打标记、从门禁里挪出去单独跑，并限期修复——门禁的可信度比覆盖率高。
2. 缓存惹的祸。为了快而缓存依赖，结果出现"本地能过、CI 挂了"的诡异问题。缓存 key 里必须带上锁文件的哈希，依赖变更时缓存自动失效。
3. 密钥管理随意。把生产密钥塞进仓库变量、在日志里打印。做法是密钥只放在 CI 的加密变量里、按环境隔离，并避免在命令输出里回显。
4. 重复触发不取消。同一条分支连推几次，多个流水线并行跑，既浪费额度又会让部署顺序错乱。开启"并发分组 + 取消旧的运行"。

我们给新项目的默认基线

迎临给每个新项目默认配一条基线流水线：GitHub Actions（或客户自建 GitLab CI），包含静态检查、单元测试、构建、部署到测试环境四步，加上依赖缓存与并发取消，YAML 大约五十行。客户团队通常一两天就能跑通并看到效果——之后所有门禁都在这条骨架上加，而不是另起一套。

如果你正打算给团队引入流水线，或者现有 CI 慢到没人愿意等，可以把当前的流程发给我们看看；我们做过的项目里，从"每次手动发布"到"提交即可自动上测试环境"通常不需要大改造。联系我们聊聊。