1 / 4概念
CI/CD
持续集成(Continuous Integration, CI)把每次变更放进同一条自动化验证流水线;持续交付/部署(Continuous Delivery/Deployment, CD)把通过验证的产物自动送到环境。判断标准不是流水线有多少阶段,而是失败能否被快速、准确定位。
1 概念
1.1 一句话定义
CI/CD 是一条由代码提交触发的有向无环图:每个作业在隔离的 runner 上取代码、恢复缓存、安装依赖、执行检查、产出制品,并把结果回写到提交或部署环境。
1.2 它解决什么问题
- 集成地狱:分支各自开发数周,合并时才发现冲突和回归。
- 手工发布漂移:谁在什么环境执行了哪条命令,无法复现。
- 发布不可追溯:制品与提交、依赖、配置之间没有稳定关联。
没有 CI/CD,验证靠人记、发布靠手敲、回滚靠猜。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 分支、提交与历史整理 | Version Control |
| lint、格式与质量门禁规则 | Code Quality |
| 私有依赖与制品托管 | Private Registry |
| 签名、SBOM 与依赖扫描 | Supply Chain Security |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| pipeline | 作业与依赖关系组成的 DAG | 不是单个脚本 |
| job | 在一个 runner 上执行的工作单元 | 默认不共享工作区 |
| runner | 执行 job 的机器或容器 | 共享 runner 不等于共享状态 |
| artifact | 跨 job 或跨运行保留的产物 | 不是缓存 |
| cache | 加速重复构建的可丢弃数据 | 不保证命中 |
| matrix | 同一 job 的参数展开 | 不是并行度设置 |
| gate | 进入下一阶段前的强制检查 | 不是“建议” |
| OIDC | 用短期令牌换取云权限 | 不是静态密钥 |
2 机制
2.1 心智模型
把流水线想成一条可重放的验证链:输入是提交 SHA、配置、密钥和缓存,输出是测试结果、制品和部署状态。每个 job 都从干净环境开始,只有显式声明的 artifact 能跨 job 传递。
2.2 机制拆解
- 触发:push、PR、tag、定时、手动或外部 webhook 产生一次 run。
- 调度:平台分配 runner,挂载代码与密钥,设置超时和并发。
- 准备:checkout、安装运行时、恢复缓存、安装依赖。
- 验证:lint、类型检查、单元/集成/E2E、构建、扫描。
- 产出:上传 artifact,记录提交、依赖和配置的关联。
- 发布:按环境推进,执行迁移、灰度、健康检查和回滚。
- 收尾:清理缓存与临时资源,回写状态和通知。
2.3 完整枚举
| 阶段 | 目的 | 输入 | 输出 | 常见失败点 |
|---|---|---|---|---|
| checkout | 取到准确提交 | SHA、凭据 | 工作区 | 权限、浅克隆缺历史 |
| setup | 固定运行时 | 版本文件 | 解释器/工具 | 版本漂移 |
| cache restore | 加速依赖 | 缓存 key | 依赖目录 | key 不匹配、缓存污染 |
| install | 还原依赖图 | lockfile、registry | node_modules 等 | 认证、网络、peer 冲突 |
| lint/typecheck | 静态检查 | 源码、规则 | 报告 | 规则版本不一致 |
| test | 行为验证 | 源码、测试数据 | 报告、覆盖率 | flaky、环境差异 |
| build | 产出可发布物 | 源码、构建参数 | artifact | 非确定性、OOM |
| scan/sign | 安全与来源 | artifact、SBOM | 证明 | 漏洞库、签名失败 |
| deploy | 推进环境 | artifact、配置 | 新版本 | 迁移、权限、超时 |
| verify | 确认发布成功 | 健康检查、指标 | 通过/回滚 | 检查太浅、指标延迟 |
触发方式:
| 触发 | 适用 | 注意 |
|---|---|---|
| push | 主干与分支验证 | 避免每个分支都跑全量 |
| pull request | 合并前门禁 | fork PR 默认无密钥 |
| tag | 发布 | tag 必须不可变 |
| schedule | 夜间回归、依赖扫描 | 结果要有人看 |
| manual | 生产发布、回滚 | 需要审批与审计 |
| webhook | 外部系统联动 | 需要验签与重放保护 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 缓存命中 | 70%–95% | lockfile 哈希做 key 时较稳 |
| 单 job 超时 | 10–60 分钟 | 按任务设置,不要默认无限 |
| artifact 保留 | 7–90 天 | 受合规与存储成本约束 |
| 并行 matrix | 2–20 个 | 受配额与依赖服务限制 |
| 反馈目标 | 10 分钟内 | 超过后开发者会绕过流水线 |
3 实践
3.1 最小示例
name: ci
on:
pull_request:
push: {branches: [main]}
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
node: [20, 22]
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with: {version: 9}
- uses: actions/setup-node@v4
with: {node-version: '${{ matrix.node }}', cache: pnpm}
- run: pnpm install --frozen-lockfile
- run: pnpm lint && pnpm test && pnpm build
3.2 常用操作与参数
| 操作 | GitHub Actions | Jenkins | 说明 |
|---|---|---|---|
| 触发 | on: | triggers / webhook | 明确事件与分支过滤 |
| 缓存 | actions/cache / setup 缓存 | stash / 插件 | key 用 lockfile 哈希 |
| 制品 | upload-artifact | archiveArtifacts | 保留期与访问权限 |
| 密钥 | secrets / OIDC | Credentials / Vault | 最小权限、短期令牌 |
| 矩阵 | strategy.matrix | matrix 指令 | 控制组合爆炸 |
| 并发 | concurrency | disableConcurrentBuilds | 同分支取消旧运行 |
3.3 标准流程
- 先定义门禁,并固定运行时、包管理器与 CLI 版本。
- 用 lockfile 哈希做缓存 key,缓存只存可重建的数据。
- 把测试拆成快慢两层:PR 跑快反馈,主干/夜间跑全量。
- 构建一次,产出不可变 artifact,后续环境复用同一份。
- 发布用 OIDC/短期凭据,执行迁移、健康检查和回滚脚本。
- 每次失败保留日志、artifact 和可复现命令,修完补回归。
3.4 与相邻技术的组合
- 版本控制:分支保护要求必需检查通过;提交 SHA 关联制品。
- 代码质量:lint/质量门禁在 CI 执行,规则版本随仓库锁定。
- 私有仓库:CI 用只读凭据拉包,发布用最小写权限。
- 容器/云原生:镜像构建、扫描、签名、部署构成一条供应链。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 托管方式 | SaaS / 自建 | 维护成本与网络边界 |
| 生态 | GitHub / GitLab / Jenkins | 与代码托管和插件的耦合 |
| 弹性 | 托管 runner / 自管集群 | 排队时间与成本 |
| 配置语言 | YAML / Groovy / 代码 | 学习曲线与复用方式 |
| 安全 | OIDC / 静态密钥 / 审批 | 供应链与权限风险 |
3.6 决策规则
- 代码在 GitHub、团队小:GitHub Actions,优先 OIDC 和托管 runner。
- 已有 Jenkins 插件与自管集群:保留 Jenkins,但把 Jenkinsfile 纳入版本控制。
- 需要强审批、合规审计:选择支持环境审批与审计日志的平台。
- 构建需要特殊硬件/内网:自管 runner,按标签调度。
- 矩阵超过 10 个组合:先拆必跑与可选,避免配额和时长失控。
- 发布频率高:构建一次、制品晋级,不要每个环境重新构建。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| GitHub Actions | 生态近、YAML 简单、OIDC 成熟 | 复杂流水线受表达力限制 | GitHub 项目 |
| Jenkins | 插件多、自管可控 | 维护重、Groovy 复杂 | 内网、历史项目 |
| GitLab CI | 与仓库/制品/环境一体 | 自管成本高 | GitLab 用户 |
| Buildkite | 混合云、自管 agent 灵活 | 需要自己编排 | 大规模自管 |
3.8 何时不该用
- 单人一次性脚本:本地跑更快,不必建流水线。
- 没有测试和门禁:流水线只是把手工命令自动化,不会提高质量。
- 每次发布都重新构建:制品不可复现,回滚无法保证同一份。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 本地通过、CI 失败 | 运行时/依赖/环境变量不同 | 固定版本,打印环境,用容器复现 |
| 缓存恢复后行为异常 | 缓存 key 太宽或缓存被污染 | 用 lockfile 哈希,定期清理 |
| fork PR 拿不到密钥 | 平台默认不注入 | 用受限工作流或维护者触发 |
| 测试偶发失败 | 时序、共享资源、随机数据 | 隔离、重试仅限瞬时故障、记录 flaky |
| 部署一半失败 | 迁移与代码不兼容 | 向前兼容迁移,支持回滚 |
| runner 磁盘满 | 缓存/镜像/日志堆积 | 清理策略与容量告警 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
在 CI 里 npm install 不用 lockfile | 每次依赖漂移 | --frozen-lockfile |
| 把密钥写进仓库变量 | 泄露面扩大 | OIDC/短期凭据 |
| 所有分支跑全量 E2E | 排队与成本失控 | PR 快检,主干全量 |
| 失败后无限重试 | 掩盖真实缺陷 | 只重试瞬时故障并记录 |
4.3 可观测信号
排队时长、job 成功率、P50/P95 时长、缓存命中率、flaky 率、artifact 上传大小、部署失败率与回滚次数。失败日志要能直接定位到阶段和命令。
4.4 安全 / 性能 / 一致性边界
- 安全:CI 是供应链入口;密钥最小权限、OIDC 短期令牌、依赖固定版本。
- 性能:反馈时间超过十分钟,开发者会绕过门禁;先优化缓存和分层测试。
- 一致性:同一提交、同一工具链、同一 lockfile 必须产出同一制品。