先说个很现实的场景三个人以内的小团队本地开发顺风顺水代码一推上去就出问题——有人忘提交 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 ActionsGitLab 仓库配 GitLab CI这条原则能省掉大量的 token 配置和回调调试工作。真要说差异GitLab CI 的 runner 可以自建并且长期驻留适合有内网依赖、需要固定构建机的团队GitHub Actions 的托管 runner 开箱即用省掉了运维成本但如果需要访问内网资源就得自建 self-hosted runner那时候运维负担又回来了。还有一点是镜像生态GitHub Marketplace 上的现成 Action 数量庞大uses: xxx/yyyv1一行就能接入GitLab 那边更多是靠在 script 里写命令。我个人的实际做法是开源项目、个人项目、以及不需要访问内网的业务仓库直接上 GitHub Actions公司内部有严格网络隔离要求、构建产物必须留在自己机房的项目才考虑自建 runner 或者留在 GitLab 体系里。这种取舍没有标准答案别为了统一而统一迁移本身的成本经常被低估。注意不管用哪个平台CI 配置文件里的关键动作版本要固定。uses: actions/checkoutv4这种写法比main稳得多极端情况下可以固定到 commit sha避免上游 action 更新后把你的流水线搞挂。2. 手写第一个能跑起来的 workflow2.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/checkoutv4 - name: 安装 Node uses: actions/setup-nodev4 with: node-version: 20 cache: npm - name: 安装依赖 run: npm ci - name: 执行测试 run: npm testpermissions: 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的取值要按仓库实际情况调整如果是发布类 workflowcancel-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/cachev4 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-latestfail-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-artifactv4 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。先看 DockerfileFROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM nginx:1.27-alpine COPY --frombuilder /app/dist /usr/share/nginx/html EXPOSE 80这个多阶段写法的用意是减小最终镜像体积。构建阶段需要完整的 Node 环境和 node_modules运行时只需要静态文件和一个 nginx两者分开之后镜像能从几百兆压到几十兆。COPY package*.json单独放在COPY . .之前是为了利用 Docker 的层缓存只要依赖清单没变npm ci这一层就能复用改业务代码不会触发重装。再看 workflowname: build-and-push on: push: tags: [v*] jobs: build: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: actions/checkoutv4 - uses: docker/setup-buildx-actionv3 - uses: docker/login-actionv3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - uses: docker/metadata-actionv5 id: meta with: images: ghcr.io/${{ github.repository }} - uses: docker/build-push-actionv5 with: context: . push: true tags: ${{ steps.meta.outputs.tags }} labels: ${{ steps.meta.outputs.labels }} cache-from: typegha cache-to: typegha,modemax几个关键点。permissions里的packages: write是推镜像到 GitHub 容器仓库所必需的不声明就会 403。metadata-action负责从 git tag 自动生成镜像标签省得手写。cache-from和cache-to用typegha把构建层缓存存到 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/actionmain这种写法意味着上游任何一次提交都会立刻作用到你的流水线供应链风险的入口就在这。4.3 三种常见的部署落地方式部署环节的形态取决于你的基础设施。我经手过的大致三类。第一类是部署到对象存储或者静态托管适合前端项目。构建产物上传之后直接生效没有服务器要维护。这类部署的可靠性最高出错概率最低回滚就是把上一个版本的产物重新上传。第二类是通过 SSH 连到目标服务器执行命令适合自建服务器的小团队deploy: needs: test if: github.ref refs/heads/main runs-on: ubuntu-latest environment: production steps: - name: 远程执行 uses: appleboy/ssh-actionv1 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 -fneeds: test保证测试 Job 成功后才部署这条依赖关系别漏。docker image prune -f是我强制加的服务器磁盘被旧镜像塞满是这类方案最典型的故障隔一段时间就清理一次能省不少事。第三类是通过云平台的 API 触发滚动更新适合已经在用容器编排的场景。这类方式的好处是平台自己处理健康检查和回滚但要处理的凭据类型更多配置也复杂。三种方式的共同点是部署前一定要有回滚路径。没有回滚方案的自动化部署本质上是在给自己增加风险面。5. 常见问题排查与实操避坑5.1 高频报错速查表下面这张表是我自己遇到和帮别人看过的问题里出现频率最高的几类按症状整理症状大概率原因处理方式workflow 完全没触发文件不在.github/workflows/下或者分支/路径过滤不匹配检查目录和on的过滤条件先临时去掉过滤跑一次报 403 无权限permissions声明过窄或 token 缺少packages: write等按需补权限遵循最小化原则逐个加npm ci报 lock 不同步package.json改了但 lock 没提交本地重新npm install并提交 lock 文件缓存看起来命中了但还是慢缓存键设计不合理或者 Job 失败导致缓存未写入用hashFiles生成键检查 Job 是否成功结束secrets 在 PR 里为空fork 的 PR 默认拿不到仓库 secrets接受限制或者改用受控的触发方式runner 磁盘空间不足构建产物过大或者旧镜像未清理加清理步骤必要时用更大规格的 runner部署步骤被跳过if条件不满足或者needs的前置 Job 失败从日志顶部往下看第一个失败点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 分支推送时执行。第三条是留住失败现场。测试失败时把日志、截图、覆盖率报告都传成 artifactif: 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 节那份最小模板开始把它跑绿。跑绿之后再回头看权限和缓存那两节会觉得顺理成章很多。这套东西的门槛主要不在语法而在于理解每一步为什么要这么写理解到位之后后面加什么功能都只是查文档的问题。