---
title: 工具-08-CICD入门
aliases:
  - CI/CD
  - 持续集成
  - 持续交付
  - GitHub Actions
tags:
  - 工具/工程化
  - 类型/教程
created: 2026-10-11
updated: 2026-10-11
level: 进阶
prerequisites:
  - "[[工具-01-Git版本控制]]"
  - "[[工具-04-测试基础]]"
sources:
  - https://docs.github.com/zh/actions
  - https://docs.gitlab.com/ee/ci/
  - https://docs.docker.com/build/ci/
  - https://learn.microsoft.com/zh-cn/dotnet/core/tools/
---

# 工具-08-CICD入门

> [!abstract] 这一篇讲什么
> CI/CD 是**把「构建—测试—发布」这套动作从人手里交给机器**的工程实践。
> 本篇覆盖：三个缩写的确切区别、流水线该有哪些阶段、GitHub Actions 与 GitLab CI 怎么写、
> 缓存与并行怎么做、密钥怎么管，以及一条能直接改改就用的完整流水线。

## 一、是什么：CI / CD 分别指什么

三个词经常被混用，但含义不同：

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

> [!important] 一句话区分两种 CD
> **Delivery 是"随时能发"，Deployment 是"自动就发"。**前者留一个人工闸门，后者没有。
> 对大多数团队，先做到 Delivery 就够了；Deployment 需要很强的测试与监控才敢上。

## 二、为什么需要它

> [!warning] 手工发布的典型现场
> 发布前两小时：有人在群里问"这次发哪几个文件？"
> 有人手动 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 分钟 | 环境或权限问题 |

> [!tip] 顺序原则：便宜的放前面
> 「格式化检查 5 秒」放在「跑 10 分钟测试」之前，可以省下大量等待。
> 反过来（先跑测试再检查格式）会让每次格式错误都浪费 10 分钟。

### 3.2 触发策略

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

> [!important] `pull_request` 与 `push` 的区别
> `push` 在**分支推送后**触发，`pull_request` 在 **PR 创建/更新时**触发，且默认在**合并结果的上下文**中运行。
> 要拦住坏代码，PR 门禁必须配 `pull_request`，并把它设为分支保护的必需检查。

### 3.3 GitHub Actions 的基本结构

四个概念，从大到小：

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

一段可用的最小工作流：

```yaml
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
```

> [!note] 关于 `npm ci` 与 `npm install`
> 流水线里必须用 `npm ci`：它严格按 `package-lock.json` 安装，且会先清空 `node_modules`，
> 保证构建可复现。`npm install` 可能悄悄升级次要版本，导致"昨天还能过今天就挂"。见 [[工具-03-包管理器]]。

### 3.4 .NET 项目的流水线

```yaml
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
```

> [!tip] 为什么用 `--no-restore` / `--no-build`
> 每个 `dotnet` 命令默认都会隐式还原或构建。在流水线里拆成显式步骤并加 `--no-*`，
> 可以避免重复劳动，也让每一步的耗时与失败原因更清晰。见 [[CSharp-07-dotnet项目与工具链]]。

### 3.5 GitLab CI 对照

GitLab 把配置放在仓库根目录的 `.gitlab-ci.yml`，用「阶段（stage）」组织：

```yaml
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 Actions | GitLab CI |
|---|---|---|
| 配置位置 | `.github/workflows/*.yml` | `.gitlab-ci.yml` |
| 执行单元 | Job | Job |
| 阶段划分 | `needs` 表达依赖 | `stages` 顺序执行 |
| 复用现成逻辑 | `uses:` 引用 Action | `include:` 引用模板 |
| 运行环境 | Runner（`runs-on`） | Runner（`tags`） |
| 变量与密钥 | Secrets / Variables | CI/CD Variables |

> [!note] 选择建议
> 代码在 GitHub 就用 Actions，在 GitLab 就用 GitLab CI——同平台集成度最高、配起来最省事。
> 两者的概念几乎一一对应，学会一个，另一个半天就能上手。以官方最新文档为准。

### 3.6 缓存与并行

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

| 手段 | 效果 | 注意 |
|---|---|---|
| 依赖缓存（`cache: npm` 等） | 通常省 50%–80% 时间 | 缓存键要包含锁文件的哈希，否则会用到过期缓存 |
| 构建产物缓存 | 增量构建更快 | 键要包含源码哈希 |
| 作业并行 | 多个独立 Job 同时跑 | 受并发额度限制，私有仓库可能计费 |
| 测试分片 | 大测试集切分到多机 | 需保证分片互不依赖 |
| 只跑受影响的测试 | 大仓库必备 | 需要依赖图分析，实现复杂 |

```yaml
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: ${{ runner.os }}-npm-
```

> [!warning] 缓存失效的三个坑
> 1. **缓存键没有包含锁文件**，依赖升级了但还在用旧缓存，出现"本地能跑 CI 不能跑"
> 2. **缓存里混进了构建产物**，导致增量构建用了错误的中间结果
> 3. **把密钥写进缓存目录**，缓存可被同仓库的其他分支读取

### 3.7 密钥与权限管理

> [!danger] 绝不要把密钥写进仓库
> 一旦提交，即使随后删除，它依然留在 Git 历史里。**唯一的正确处理是立刻轮换（作废重发）**，
> 而不只是删掉那次提交。见 [[工具-05-GitHub与GitLab协作]]。

正确做法：

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

> [!important] 第三方 Action 的风险
> `uses: some-user/some-action@v1` 相当于**执行别人写的代码**，而它能读到你的密钥。
> 缓解办法：优先用官方或知名 Action；**固定到具体 commit SHA 而不是浮动标签**；
> 定期审计仓库里用到的 Action。

### 3.8 部署与回滚

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

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

> [!tip] 部署流水线的最小可靠设计
> 1. 构建出的镜像/制品用 `commit SHA` 打标签，推送到仓库
> 2. 部署时只做"把某个 SHA 拉起来"，不再重新构建
> 3. 保留最近 N 个版本，回滚 = 把 SHA 换成上一个
> 4. 发布后用健康检查端点确认，失败自动切回

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

> [!example] 四步走
> **第 1 步**：先把"构建 + 测试"在本地写成一条命令（例如 `npm run verify`）。
> 流水线只是把这条命令搬到服务器上跑——**本地跑不通的，别指望 CI 能跑通**。
>
> **第 2 步**：创建 `.github/workflows/ci.yml`，只做检出、装依赖、跑那条命令。
>
> **第 3 步**：把该检查设为**分支保护的必需检查**，从此 PR 必须绿了才能合并。
>
> **第 4 步**：确认稳定运行两周后，再往上加"打制品"和"部署"。

> [!warning] 不要一上来就写全自动部署
> 新手最常见的失败是：第一天就写了一条"合并即上线"的流水线，然后因为一次误合并把生产搞挂。
> 顺序应该是：**先有 CI 门禁 → 再有制品 → 最后才自动化部署**。

## 五、注意事项与常见坑

> [!warning] 十个高频坑
> 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/>

> [!note] 关于版本
> 工作流语法与 Action 版本会随平台更新，`actions/checkout`、`actions/cache` 等的版本号请以官方最新文档为准。
