w wyl123ly 的博客
MD

工具-08-CICD入门

15 KB 2026.10.11 原文件

工具-08-CICD入门

这一篇讲什么

CI/CD 是把「构建—测试—发布」这套动作从人手里交给机器的工程实践。

本篇覆盖:三个缩写的确切区别、流水线该有哪些阶段、GitHub Actions 与 GitLab CI 怎么写、

缓存与并行怎么做、密钥怎么管,以及一条能直接改改就用的完整流水线。

一、是什么:CI / CD 分别指什么

三个词经常被混用,但含义不同:

缩写全称含义交付物
CIContinuous Integration(持续集成)每次提交都自动构建并跑测试,尽早发现集成问题一个"通过/失败"的信号
CDContinuous Delivery(持续交付)在 CI 基础上,自动把可发布版本准备好,但发布仍需人工点确认随时可发布的制品
CDContinuous Deployment(持续部署)上述全部自动化,通过测试即自动上线,无人工环节已上线的服务

一句话区分两种 CD

Delivery 是"随时能发",Deployment 是"自动就发"。前者留一个人工闸门,后者没有。

对大多数团队,先做到 Delivery 就够了;Deployment 需要很强的测试与监控才敢上。

二、为什么需要它

手工发布的典型现场

发布前两小时:有人在群里问"这次发哪几个文件?"

有人手动 FTP 上传,漏传一个配置文件;测试环境验证过的版本和线上跑的不是同一个;

出事之后没有人说得清"线上现在到底是哪个版本"。

手工发布的核心问题不是"慢",而是不可复现:

问题后果
步骤记在人脑里换个人就发不出去,或发出不同的东西
环境靠手工配置"在我机器上能跑"(见 [[后端-07-Docker与容器化]])
没有自动化测试门禁把已知会挂的代码发上去
没有版本对应关系出问题无法快速定位与回滚

CI/CD 带来的四件事:

  1. 快速反馈:提交后几分钟就知道有没有弄坏东西
  2. 可复现:同一个提交永远产出同一份制品
  3. 降低发布恐惧:发布变成日常动作,而不是月度大事
  4. 把知识写成代码:流水线文件本身就是"怎么发版"的文档

三、核心内容

3.1 流水线应该有哪些阶段

一条健康的流水线是由快到慢、由便宜到昂贵排列的——这样失败得越早,浪费越少。

阶段做什么典型耗时失败意味着
1. 检出与准备拉代码、装依赖(用缓存)10–60 秒依赖或网络问题
2. 静态检查格式化、Lint、类型检查10–60 秒代码规范或类型错误
3. 构建编译 / 打包1–5 分钟编译错误
4. 测试单元 → 集成 → 端到端1–15 分钟逻辑错误
5. 制品生成镜像 / 可执行文件并打标签1–5 分钟打包配置问题
6. 部署推送到环境(可选人工确认)1–10 分钟环境或权限问题

顺序原则:便宜的放前面

「格式化检查 5 秒」放在「跑 10 分钟测试」之前,可以省下大量等待。

反过来(先跑测试再检查格式)会让每次格式错误都浪费 10 分钟。

3.2 触发策略

触发方式配置关键字(Actions 为例)适用场景
推送到分支on: push常规 CI
针对 PRon: pull_request合并前门禁(最重要)
打标签on: push: tags: ['v*']发版
定时on: schedule(cron)夜间全量测试、依赖审计
手动on: workflow_dispatch紧急重发、指定环境部署

pull_request 与 push 的区别

push 在分支推送后触发,pull_request 在 PR 创建/更新时触发,且默认在合并结果的上下文中运行。

要拦住坏代码,PR 门禁必须配 pull_request,并把它设为分支保护的必需检查。

3.3 GitHub Actions 的基本结构

四个概念,从大到小:

Workflow(.github/workflows/*.yml)
└── Job(默认并行,可 needs 串行)
    └── Step(顺序执行)
        └── uses: 复用别人写好的 Action  |  run: 直接跑命令

一段可用的最小工作流:

name: CI

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '24'
          cache: npm            # 自动缓存依赖,省下大量时间

      - run: npm ci             # ci 而非 install:严格按锁文件安装
      - run: npm run lint
      - run: npm test

关于 npm ci 与 npm install

流水线里必须用 npm ci:它严格按 package-lock.json 安装,且会先清空 node_modules,

保证构建可复现。npm install 可能悄悄升级次要版本,导致"昨天还能过今天就挂"。见 工具-03-包管理器。

3.4 .NET 项目的流水线

name: dotnet-ci

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'
      - run: dotnet restore
      - run: dotnet build --no-restore -c Release
      - run: dotnet test --no-build -c Release --logger "trx"
      - run: dotnet publish -c Release -o out

为什么用 --no-restore / --no-build

每个 dotnet 命令默认都会隐式还原或构建。在流水线里拆成显式步骤并加 --no-*,

可以避免重复劳动,也让每一步的耗时与失败原因更清晰。见 CSharp-07-dotnet项目与工具链。

3.5 GitLab CI 对照

GitLab 把配置放在仓库根目录的 .gitlab-ci.yml,用「阶段(stage)」组织:

stages: [lint, test, build]

lint:
  stage: lint
  image: node:24
  script:
    - npm ci
    - npm run lint

test:
  stage: test
  image: node:24
  script:
    - npm ci
    - npm test

build:
  stage: build
  image: docker:latest
  services: [docker:dind]
  script:
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  only: [main]

两平台的概念对应关系:

概念GitHub ActionsGitLab CI
配置位置.github/workflows/*.yml.gitlab-ci.yml
执行单元JobJob
阶段划分needs 表达依赖stages 顺序执行
复用现成逻辑uses: 引用 Actioninclude: 引用模板
运行环境Runner(runs-on)Runner(tags)
变量与密钥Secrets / VariablesCI/CD Variables

选择建议

代码在 GitHub 就用 Actions,在 GitLab 就用 GitLab CI——同平台集成度最高、配起来最省事。

两者的概念几乎一一对应,学会一个,另一个半天就能上手。以官方最新文档为准。

3.6 缓存与并行

流水线最常见的时间浪费是重复下载依赖。

手段效果注意
依赖缓存(cache: npm 等)通常省 50%–80% 时间缓存键要包含锁文件的哈希,否则会用到过期缓存
构建产物缓存增量构建更快键要包含源码哈希
作业并行多个独立 Job 同时跑受并发额度限制,私有仓库可能计费
测试分片大测试集切分到多机需保证分片互不依赖
只跑受影响的测试大仓库必备需要依赖图分析,实现复杂
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: ${{ runner.os }}-npm-

缓存失效的三个坑

1. 缓存键没有包含锁文件,依赖升级了但还在用旧缓存,出现"本地能跑 CI 不能跑"

2. 缓存里混进了构建产物,导致增量构建用了错误的中间结果

3. 把密钥写进缓存目录,缓存可被同仓库的其他分支读取

3.7 密钥与权限管理

绝不要把密钥写进仓库

一旦提交,即使随后删除,它依然留在 Git 历史里。唯一的正确处理是立刻轮换(作废重发),

而不只是删掉那次提交。见 工具-05-GitHub与GitLab协作。

正确做法:

做法说明
平台密钥存储GitHub Secrets / GitLab CI Variables,只在运行时注入
环境级隔离生产密钥只允许受保护分支/环境访问
最小权限令牌CI 令牌只给需要的权限,不要用个人全权限令牌
令牌有效期设置过期时间,定期轮换
日志脱敏确保密钥不会被 echo 进日志(平台会遮蔽已登记的密钥)

第三方 Action 的风险

uses: some-user/some-action@v1 相当于执行别人写的代码,而它能读到你的密钥。

缓解办法:优先用官方或知名 Action;固定到具体 commit SHA 而不是浮动标签;

定期审计仓库里用到的 Action。

3.8 部署与回滚

发布流水线要回答三个问题:发什么、发去哪、怎么退。

关注点做法
制品唯一标识用提交 SHA 或语义化版本打标签,绝不用 latest
环境区分dev / staging / prod 分开配置,生产需人工批准
数据库变更与应用解耦,先兼容后清理(见 [[后端-08-部署与运维基础]])
回滚保留上一版制品,回滚是换回旧制品而不是重新构建
发布后验证自动跑冒烟测试与健康检查,失败自动回滚

部署流水线的最小可靠设计

1. 构建出的镜像/制品用 commit SHA 打标签,推送到仓库

2. 部署时只做"把某个 SHA 拉起来",不再重新构建

3. 保留最近 N 个版本,回滚 = 把 SHA 换成上一个

4. 发布后用健康检查端点确认,失败自动切回

四、怎么用:从零加一条流水线

四步走

第 1 步:先把"构建 + 测试"在本地写成一条命令(例如 npm run verify)。

流水线只是把这条命令搬到服务器上跑——本地跑不通的,别指望 CI 能跑通。

第 2 步:创建 .github/workflows/ci.yml,只做检出、装依赖、跑那条命令。

第 3 步:把该检查设为分支保护的必需检查,从此 PR 必须绿了才能合并。

第 4 步:确认稳定运行两周后,再往上加"打制品"和"部署"。

不要一上来就写全自动部署

新手最常见的失败是:第一天就写了一条"合并即上线"的流水线,然后因为一次误合并把生产搞挂。

顺序应该是:先有 CI 门禁 → 再有制品 → 最后才自动化部署。

五、注意事项与常见坑

十个高频坑

1. 流水线依赖开发者本机状态:CI 环境是干净的,任何"我本地有这个文件"都会失败

2. 用了浮动版本的依赖或 Action:今天过明天挂,原因是被上游改了

3. 测试有顺序依赖:本地按文件名顺序跑能过,CI 并行跑就挂

4. 在 CI 里跑需要人工交互的命令:会一直挂到超时

5. 日志里打印了密钥:即使平台遮蔽,也可能被绕过(如 base64 后打印)

6. 把 CI 当万能钥匙:给 CI 令牌过高权限,一台 Runner 被攻破就全盘皆输

7. 没有超时设置:卡死的 Job 会长时间占用额度甚至阻塞队列

8. 忽略 flaky 测试:重跑能过就不管,最后所有人都学会"点一下重试",门禁形同虚设

9. 缓存与制品混用:把构建产物当缓存,导致用错版本

10. 没有失败通知:红了的流水线没人看,等于没有门禁

六、练习题

  1. 基础题:为一个 Node 项目写一条流水线,要求:PR 触发、做 Lint 和测试、启用 npm 缓存、使用 npm ci。
  2. 进阶题:你的测试有 3000 个用例、耗时 25 分钟,已成为瓶颈。请给出至少三种提速方案,并说明各自的适用条件与风险。
  3. 进阶题:设计一条"打标签即发布"的流水线:要求版本号来自 Git 标签、制品用该版本打标签、生产部署需要人工批准。
  4. 思考题:如果团队里所有人都习惯"CI 红了就点重试",这条流水线还有价值吗?应该怎么治理?

七、常见问题(FAQ)

Q:小项目(一个人)也需要 CI 吗?

A:需要,但可以极简——只做"构建 + 测试"这一条。它的价值不是给别人看,而是让你在改动之后立刻知道有没有弄坏东西;一个人更容易忘记上次改了什么。

Q:CI 很慢,团队开始绕过它,怎么办?

A:把"快"当成和"对"同等的需求来做:先缓存依赖,再把能并行的拆开,然后把慢测试挪到夜间全量跑,PR 只跑受影响的部分。门禁太慢必然被绕过,这是管理问题也是技术问题。

Q:自建 Runner 还是用托管?

A:先用托管(省事、按量计费);当出现以下情况再考虑自建:需要访问内网资源、需要特定硬件、构建量很大导致成本明显偏高。

Q:CI 里要不要跑端到端测试?

A:要,但只跑核心路径。E2E 慢且不稳定(flaky),把它放在合并到主分支之后或夜间跑,PR 阶段用单元与集成测试兜住。见 工具-04-测试基础。

相关笔记

  • 工具-04-测试基础:门禁里跑的到底是什么
  • 工具-05-GitHub与GitLab协作:分支保护与 PR 评审流程
  • 工具-01-Git版本控制:标签与版本号
  • 后端-07-Docker与容器化:在流水线里构建与推送镜像
  • 后端-08-部署与运维基础:发布策略与回滚
  • CSharp-07-dotnet项目与工具链:.NET 项目的构建与发布命令

参考来源

  • GitHub Actions 官方文档(中文):<https://docs.github.com/zh/actions>
  • GitLab CI/CD 官方文档:<https://docs.gitlab.com/ee/ci/>
  • Docker 官方文档《Build with CI》:<https://docs.docker.com/build/ci/>
  • .NET CLI 官方文档(中文):<https://learn.microsoft.com/zh-cn/dotnet/core/tools/>

关于版本

工作流语法与 Action 版本会随平台更新,actions/checkout、actions/cache 等的版本号请以官方最新文档为准。