GitHub Actions 实战：从最小 CI 到 Docker 镜像与自动部署

先说个很现实的场景：三个人以内的小团队，本地开发顺风顺水，代码一推上去就出问题——有人忘提交 lock 文件，有人 Node 版本是 18、有人是 22，测试在 A 的机器上全绿，在 B 的机器上红一片。问题的根子通常不在代码写得好不好，而是"验证"这件事没有统一的入口。github ci 就是把这套验证从个人电脑搬到统一环境里的东西，具体到实现层面，绝大多数人用的就是 GitHub 自带的 GitHub Actions。这篇文章不讲空泛概念，我按自己给几个仓库搭流水线的顺序，从最小可用的 workflow 写到镜像构建和自动部署，把参数、缓存键、权限、排查手段全部拆开说清楚，中间会交代每一步为什么这么选。刚接触 CI/CD 的新手能照着抄，已经用过 GitLab CI 想迁过来的人，也能在对比里找到对应关系的替换点。

1. 先搞清楚 GitHub CI 的边界，别一上来就堆配置

1.1 它到底替你做了哪些事

很多人对 CI 的理解停留在"自动跑测试"，这其实只说对了一小半。一套完整的持续集成要解决四件事：代码合并前的静态检查与测试、构建产物的一致性、产物的归档与分发、以及部署动作的触发与回滚能力。GitHub Actions 把这四件事拆成可组合的任务单元，跑在 GitHub 提供的临时虚拟机上，每次运行都是一台干净的环境，跑完销毁。这一点很关键，它意味着你不需要维护一台长期在线的构建服务器，也不用担心上一轮的残留文件影响下一轮结果。

我拿一个前端仓库举例。以前的做法是本地npm run build打包完手动传到服务器，或者写个脚本 rsync 过去。这套流程最致命的问题是不可追溯——线上这个 dist 目录到底是哪个 commit 打出来的，没人说得清。换成 Actions 之后，每次 push 都会生成一份绑定 commit sha 的产物，出问题可以精确回退到某个构建版本。这就是 CI 带来的第一层价值：让"哪个版本的代码变成了哪份产物"这件事有据可查。

第二层价值在于它是一道门禁。仓库开启分支保护规则后，可以把 CI 的检查结果设为合并的必要条件，测试不过就合不进去。这个约束比口头约定强得多，团队人数一多，靠自觉是撑不住的。

1.2 Workflow、Job、Step、Action 四层概念一次讲透

这四个词是读官方文档时最先卡住的地方，我用做菜的类比把它们串起来。Workflow 是"今天要做的一桌菜"，对应.github/workflows/目录下的一个 yaml 文件；Job 是"其中的一道菜"，每个 Job 默认跑在一台独立的虚拟机上，互相之间不共享文件系统；Step 是"这道菜里的一个操作步骤"，按顺序执行，共享同一个 Job 的工作目录；Action 是"可以复用的半成品料包"，比如官方提供的actions/checkout负责拉代码，actions/setup-node负责装 Node 环境。

理解 Job 之间互相隔离这一点非常重要，它解释了新手最常问的一个问题：为什么我在上一个 Job 里npm install装好的依赖，到了下一个 Job 又要重装一遍。因为那是两台不同的机器。如果确实需要跨 Job 传递文件，得用actions/upload-artifact和actions/download-artifact显式搬运。

另一个容易忽略的点是 Step 的失败传播。默认情况下，任何一个 Step 返回非零退出码，整个 Job 立刻中断，后续 Step 不再执行，Job 标记为失败。这个默认行为大部分时候是对的，但清理现场、上传测试报告这类收尾动作会被连累跳过，后面我会讲怎么用if: always()兜住。

1.3 和 GitLab CI 的取舍：什么时候该换、什么时候别折腾

市面上做 CI/CD 的平台不少，很多人问过我要不要在两个平台之间迁移。我的判断标准很朴素：代码仓库在哪，CI 就尽量用哪家的，因为集成成本最低。GitHub 仓库配 GitHub Actions，GitLab 仓库配 GitLab CI，这条原则能省掉大量的 token 配置和回调调试工作。

真要说差异，GitLab CI 的 runner 可以自建并且长期驻留，适合有内网依赖、需要固定构建机的团队；GitHub Actions 的托管 runner 开箱即用，省掉了运维成本，但如果需要访问内网资源就得自建 self-hosted runner，那时候运维负担又回来了。还有一点是镜像生态，GitHub Marketplace 上的现成 Action 数量庞大，uses: xxx/yyy@v1一行就能接入，GitLab 那边更多是靠在 script 里写命令。

我个人的实际做法是：开源项目、个人项目、以及不需要访问内网的业务仓库，直接上 GitHub Actions；公司内部有严格网络隔离要求、构建产物必须留在自己机房的项目，才考虑自建 runner 或者留在 GitLab 体系里。这种取舍没有标准答案，别为了统一而统一，迁移本身的成本经常被低估。

注意：不管用哪个平台，CI 配置文件里的关键动作版本要固定。uses: actions/checkout@v4这种写法比@main稳得多，极端情况下可以固定到 commit sha，避免上游 action 更新后把你的流水线搞挂。

2. 手写第一个能跑起来的 workflow

2.1 目录结构与最小可用模板

配置文件的位置是写死的，必须是仓库根目录下的.github/workflows/，文件名随意，扩展名用.yml或.yaml都行。一个仓库里可以放多个 workflow 文件，比如ci.yml管测试，deploy.yml管发布，它们互相独立运行。

下面这份是我给一个 Node 项目写的最小可用版本，可以直接抄：

name: ci on: push: branches: [main] pull_request: branches: [main] permissions: contents: read jobs: test: runs-on: ubuntu-latest timeout-minutes: 15 steps: - name: 拉取代码 uses: actions/checkout@v4 - name: 安装 Node uses: actions/setup-node@v4 with: node-version: 20 cache: npm - name: 安装依赖 run: npm ci - name: 执行测试 run: npm test

permissions: contents: read这一行很多人会漏掉。它的作用是收窄自动生成的GITHUB_TOKEN权限，默认情况下这个 token 的权限可能比你需要的宽。养成显式声明的习惯，既安全，也能避免后续误操作改了主分支内容。timeout-minutes同样建议都加上，默认超时是 360 分钟，万一某个步骤卡死，你不想让它占着资源跑六个小时。

2.2 触发条件 on 的写法与三个高频坑

on决定了什么事件能让 workflow 跑起来，常用的是push、pull_request、workflow_dispatch、schedule这几种。看起来简单，实际上坑不少。

第一个坑是分支过滤和路径过滤同时写。下面这段配置的意思是：只有推送到 main 分支、且改动涉及src/或package.json时才触发，两个条件是与的关系。

on: push: branches: [main] paths: - 'src/**' - 'package.json'

第二个坑是把pull_request和pull_request_target搞混。前者在 PR 的合并结果上运行，来自 fork 的 PR 拿不到仓库的 secrets，这是出于安全考虑的默认设计；后者运行在目标分支的上下文里，能拿到 secrets，但如果配置不当，等于把仓库凭据交到了外部提交者的代码手里。我见过有人在开源仓库上用pull_request_target配actions/checkout拉取 PR 代码再执行，这属于典型的高风险组合，别这么做。

第三个坑是 tag 触发和分支触发分不清。发布镜像通常希望 tag 推送时执行、普通分支推送时不执行，写法上要把branches换成tags，或者两者并列，靠if条件区分。如果只写了on: push，那么每次推 tag 也会触发一遍测试，白烧额度。

提示：workflow_dispatch值得单独加上。它的作用是允许你在网页上手动点按钮触发一次运行，调试阶段特别有用，不用为了验证配置反复提交空 commit。

2.3 Runner 选择、并发控制与超时设置

runs-on决定跑在什么环境上。ubuntu-latest是最常用的，速度快、计费最低；windows-latest和macos-latest主要用于需要对应系统的构建，比如打包桌面应用或者 iOS 相关产物，它们的计费倍率明显更高。如果不是非用不可，别把测试矩阵铺到三个系统上，成本会涨得很快。

并发控制是另一个实际项目里必须配的东西：

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

这段配置的效果是：同一个分支上如果连续推了三次代码，前两次还没跑完就会被取消，只保留最新一次。没有这个配置，快速连续提交会让多个任务排队，既浪费额度又拖慢反馈速度。group的取值要按仓库实际情况调整，如果是发布类 workflow，cancel-in-progress最好设为 false，避免把正在进行的部署打断。

timeout-minutes我一般设在预期耗时的三倍左右。比如测试通常跑 3 分钟，那就设 10 分钟。这个值不是越大越好，设得太大等于失去了保护作用，某个死循环卡住的时候你要等很久才能发现。

3. 让 CI 从"能跑"变成"有用"

3.1 依赖缓存怎么配才不白做

缓存是 CI 提速最直接的手段。以 npm 为例，actions/setup-node自带缓存开关，加上cache: npm就够了，它会自动读取 lock 文件生成缓存键。手动配置actions/cache的场景通常是 Python 的 pip 或者 Go 的 module：

- name: 缓存 pip uses: actions/cache@v4 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }} restore-keys: | ${{ runner.os }}-pip-

缓存键的设计是这里最值得琢磨的部分。key必须包含操作系统和依赖清单的哈希，前者是因为不同系统的产物不通用，后者是保证依赖变了缓存自动失效。restore-keys提供的是降级匹配，当前哈希找不到时，退一步复用最近一次同系统的缓存，只是命中后需要重新安装增量部分。

见过不少人用固定字符串当缓存键，比如直接写key: npm-cache。这种配置第一次跑确实快，后面就彻底失效了，因为键永远命中，内容永远是旧的，装依赖反而变成了一种"看起来有缓存"的假象。缓存这件事的逻辑是：宁可多存几份，也不要命中错的。

注意：缓存的写入发生在 Job 成功之后。如果 Job 失败了，缓存不会保存，下一次还是从零开始。调试阶段发现每次都很慢，很可能就是这个原因。

3.2 矩阵构建 matrix 的写法和 fail-fast 取舍

矩阵构建用来在多个版本、多个平台上并行验证，一个典型的 Node 测试矩阵长这样：

strategy: fail-fast: false matrix: node: [18, 20, 22] os: [ubuntu-latest, windows-latest] exclude: - node: 18 os: windows-latest

fail-fast是这里最容易做错的决定。默认值是 true，意思是任意一个组合失败，其他正在跑的会被立刻取消。好处是省资源、反馈快；坏处是你只能看到第一个失败点，修完再跑又发现第二个。我一般设成 false，尤其在版本兼容性验证的场景下，一次把问题全暴露出来比反复试错效率高得多。

exclude用来裁剪不需要的组合，include则可以额外插入一个不在笛卡尔积里的特殊组合。注意include的行为比较反直觉：它是往已有组合上加，而不是覆盖。如果矩阵里已经有 node 20 + ubuntu 这个组合，你用include再加一条 node 20 + ubuntu 并附上额外变量，结果是两条都会跑，不是替换。

矩阵维度别铺太多，两个维度各三四个取值就是十几个 Job，跑起来时间不短。我曾经为了"全面覆盖"配了 3 个 Node 版本乘 3 个系统乘 2 个数据库，结果是每次 PR 都要等十几分钟才有结果，最后砍到只剩关键组合。

3.3 npm ci 和 npm i 的区别，CI 里为什么必须选前者

这两个命令经常被混着用，但在 CI 场景下它们的差别是决定性的。npm i会读取package.json，如果发现 lock 文件里的版本和 package.json 的要求不一致，它会顺手更新 lock 文件并且装最新的符合版本。也就是说，CI 环境里跑npm i，你每次装的依赖版本都可能和本地不一样。

npm ci的行为完全不同：它严格要求 lock 文件存在，先删掉node_modules再按 lock 文件精确安装，不会修改 lock。带来的结果是安装过程完全确定，本地装到什么版本，CI 就装到什么版本。代价是它比较"固执"，如果 lock 文件和 package.json 对不上，它会直接报错退出，而不是帮你修。

这个报错恰恰是好事。它意味着有人改了package.json却忘了提交 lock 文件，这在多人协作里是高频事故。让 CI 帮你拦住，比等到线上出现诡异的依赖问题再回头查要省事得多。我在多个仓库里都见过这样的情况：本地跑得好好的，CI 上一直失败，最后发现是提交时漏了 lock。

其他包管理器也有对应命令，Python 项目的pip install -r requirements.txt配合--require-hashes类似，Go 项目可以用go mod verify。核心逻辑一致：CI 环境要的是可复现，不是灵活性。

3.4 测试报告、覆盖率与产物归档

测试跑完不等于有价值，结果得能被看到、被留存。最基础的做法是上传产物：

- name: 上传覆盖率 if: always() uses: actions/upload-artifact@v4 with: name: coverage-${{ matrix.node }} path: coverage/ retention-days: 7

这里的if: always()是重点。前面说过，某个 Step 失败会中断整个 Job，如果不加这个条件，测试失败时报告就传不上去了——而测试失败恰恰是你最需要看报告的时候。这个细节我在早期踩过，当时只看到"测试失败"，具体哪个用例挂了一无所知，因为报告根本没存下来。

retention-days建议按需设置。默认保留 90 天，对于产物比较大的项目会占用存储额度。我一般设 7 天，够用了。覆盖率报告如果想在 PR 里直接看到变化，可以接入 Codecov 这类服务，用一行 Action 配置上传，它会自动在 PR 里评论覆盖率的增减。这个功能对推动团队补测试挺有效果，数字摆在眼前比口头强调管用。

4. 从 CI 走到 CD：镜像构建与自动部署

4.1 Docker 镜像构建与推送的完整流水线

CI 跑通之后，下一步自然是想让构建好的产物直接发布出去。以容器化部署为例，完整的推送流程需要一个多阶段 Dockerfile 和一个构建 workflow。

先看 Dockerfile：

FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM nginx:1.27-alpine COPY --from=builder /app/dist /usr/share/nginx/html EXPOSE 80

这个多阶段写法的用意是减小最终镜像体积。构建阶段需要完整的 Node 环境和 node_modules，运行时只需要静态文件和一个 nginx，两者分开之后镜像能从几百兆压到几十兆。COPY package*.json单独放在COPY . .之前是为了利用 Docker 的层缓存：只要依赖清单没变，npm ci这一层就能复用，改业务代码不会触发重装。

再看 workflow：

name: build-and-push on: push: tags: ['v*'] jobs: build: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkout@v4 - uses: docker/setup-buildx-action@v3 - uses: docker/login-action@v3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - uses: docker/metadata-action@v5 id: meta with: images: ghcr.io/${{ github.repository }} - uses: docker/build-push-action@v5 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} cache-from: type=gha cache-to: type=gha,mode=max

几个关键点。permissions里的packages: write是推镜像到 GitHub 容器仓库所必需的，不声明就会 403。metadata-action负责从 git tag 自动生成镜像标签，省得手写。cache-from和cache-to用type=gha把构建层缓存存到 Actions 的缓存服务里，实测下来第二次构建能快一半以上，尤其是依赖安装那一层。

if: github.ref == 'refs/heads/main'这类分支判断在部署 Job 上很常见，作用是阻止从特性分支误发布。我一般把发布条件绑在 tag 上，语义更清晰：打了v1.2.0这个 tag 才发布，普通提交只跑测试。

4.2 Secrets、环境变量与最小权限

凭据管理是这个环节最需要克制的地方。仓库的 Secrets 配置在设置页里，配好之后在 workflow 里用${{ secrets.XXX }}引用，日志里会自动打码。听起来很安全，但有两个盲区。

第一个盲区是 fork 提交的 PR。前面提过，这类 PR 默认拿不到 secrets，所以依赖 secrets 的步骤会直接跳过或者失败。如果你希望外部贡献者的 PR 也能跑完整测试，得改用pull_request_target并非常谨慎地设计，或者接受这部分检查在合并后再跑。

第二个盲区是日志泄露。GitHub 的自动打码机制基于 secret 的值做字符串匹配，如果你在脚本里对 secret 做了加工，比如 base64 编码后再打印，打码就失效了。所以原则很简单：凭据只允许以环境变量的形式传递，永远不要 echo 出来。

environment是另一个值得用的功能。给部署 Job 指定environment: production之后，可以在仓库设置里给这个环境挂审批规则，需要指定的人点确认才继续。同时环境级别的 secrets 和仓库级别是分开的，生产凭据可以只对生产环境可见，减少误用范围。

注意：Actions 里用到的第三方 action 尽量固定到具体版本或 commit sha。uses: some/action@main这种写法意味着上游任何一次提交都会立刻作用到你的流水线，供应链风险的入口就在这。

4.3 三种常见的部署落地方式

部署环节的形态取决于你的基础设施。我经手过的大致三类。

第一类是部署到对象存储或者静态托管，适合前端项目。构建产物上传之后直接生效，没有服务器要维护。这类部署的可靠性最高，出错概率最低，回滚就是把上一个版本的产物重新上传。

第二类是通过 SSH 连到目标服务器执行命令，适合自建服务器的小团队：

deploy: needs: test if: github.ref == 'refs/heads/main' runs-on: ubuntu-latest environment: production steps: - name: 远程执行 uses: appleboy/ssh-action@v1 with: host: ${{ secrets.DEPLOY_HOST }} username: ${{ secrets.DEPLOY_USER }} key: ${{ secrets.DEPLOY_KEY }} script: | cd /srv/app docker compose pull docker compose up -d docker image prune -f

needs: test保证测试 Job 成功后才部署，这条依赖关系别漏。docker image prune -f是我强制加的，服务器磁盘被旧镜像塞满是这类方案最典型的故障，隔一段时间就清理一次能省不少事。

第三类是通过云平台的 API 触发滚动更新，适合已经在用容器编排的场景。这类方式的好处是平台自己处理健康检查和回滚，但要处理的凭据类型更多，配置也复杂。

三种方式的共同点是：部署前一定要有回滚路径。没有回滚方案的自动化部署，本质上是在给自己增加风险面。

5. 常见问题排查与实操避坑

5.1 高频报错速查表

下面这张表是我自己遇到和帮别人看过的问题里出现频率最高的几类，按症状整理：

5.2 调试手段：从日志到本地复现

Actions 的日志默认会做一定折叠，只显示每个 Step 的标题。展开后能看到完整输出，但有个细节很多人不知道：把ACTIONS_STEP_DEBUG这个 secret 设为 true，会输出更详细的过程日志，排查 action 内部行为时很有用。

本地复现是另一条路。有个叫 act 的工具可以在本地用容器跑 workflow，配好之后不用每次提交去等结果。它的局限是环境和托管 runner 不完全一致，尤其是网络和预装软件，所以只能用来验证语法和简单的逻辑，不能完全替代真实运行。

还有一种情况是 Job 卡住不动。先看是不是某个步骤在等输入，比如命令进入交互模式等待确认。在 CI 里任何需要交互的命令都要加非交互参数，npm ci、apt-get install -y这些默认就是非交互的，自己写的脚本要注意加--yes之类的标志。再就是看timeout-minutes有没有生效，超时之后 Job 会被强制终止，日志里会有明确标记。

5.3 几条我踩过坑才明白的经验

第一条是别把所有检查塞进一个 Job。有人图省事，把 lint、测试、构建全写在一个 Job 的步骤里，结果是 lint 失败后面的全不跑，反馈速度慢。拆成多个 Job 并行，虽然容器启动次数多了，但整体墙钟时间更短，而且失败原因一目了然。

第二条是 PR 场景尽量用轻量组合。给每个 PR 都跑全量矩阵、全量集成测试，成本会失控。我的做法是 PR 只跑一个主版本加 lint 和单元测试，全量矩阵放到 main 分支推送时执行。

第三条是留住失败现场。测试失败时把日志、截图、覆盖率报告都传成 artifact，if: always()一定要加。调试一次失败花的时间，往往比配置这些收尾步骤的成本高得多。

第四条是给 workflow 文件本身加注释。三个月后回来看if条件为什么这么写，没有注释基本靠猜。尤其是那些为了绕过某个平台限制而加的 hack，一定要写清楚原因。

6. 成本与投入产出：这套东西值不值得上

6.1 免费额度和计费口径

公共仓库用 GitHub 托管的 runner 是不计费的，这也是很多开源项目能放心跑大矩阵的原因。私有仓库有免费额度，超出之后按分钟计费，而且不同系统的倍率不一样，Linux 是基准，Windows 通常按两倍算，macOS 的倍率更高。这个口径意味着同样时长的构建，跑在不同系统上花的额度完全不同。

控制成本的手段有几个方向。缩短单次运行时间最直接，靠缓存和并行；减少运行次数靠concurrency的取消策略和路径过滤；减少矩阵维度靠精准选择需要覆盖的版本。我一般会给仓库定一个规则：只有 main 分支和 release 分支跑全量，PR 跑精简版，tag 才触发发布流程。这样下来额度消耗通常在可控范围内。

6.2 什么项目该上 CI，什么项目先别急

判断标准可以从两个维度看：改动频率和出错代价。改动频繁、多人协作、上线后出问题影响面大的项目，CI 的收益最明显，因为它的价值随提交次数增加而放大。反过来，一个人维护、几个月才改一次的脚本仓库，配一套精细的流水线，维护成本可能超过收益。

一个折中的起步方式是先上一件事：在 main 分支的每次推送和 PR 上跑一遍测试或者构建。这一步的配置量很小，能拦住大部分低级问题。跑顺了之后，再逐步加上缓存优化、矩阵、镜像构建、自动部署。一上来就想把整套体系搭全，容易在某个环节卡住之后失去动力。

我自己给新仓库配置的习惯是先写好最小版本提交一次，看它跑通，然后再加缓存，再加矩阵，一步一步来。每次只加一个变量，出问题的时候能立刻定位到是哪次改动引入的。这个习惯看着慢，实际上比一次性写两百行 yaml 然后对着报错挨个猜要快得多。

如果你手头正好有个仓库还没配 CI，我建议从第 2 节那份最小模板开始，把它跑绿。跑绿之后再回头看权限和缓存那两节，会觉得顺理成章很多。这套东西的门槛主要不在语法，而在于理解每一步为什么要这么写，理解到位之后，后面加什么功能都只是查文档的问题。