摘要本文以一条可直接复制运行的 GitHub Actions 流水线为主线手把手教你把「代码提交 → 自动构建 → 多版本测试 → 产物发布」串成端到端的 CI/CD 自动化流程。内容覆盖 workflow 核心概念、依赖缓存、matrix 矩阵并行测试、Artifacts 跨 Job 产物传递以及 npm 包与 Docker 镜像的自动发布并标注每个关键技术点的一手官方文档来源与权限permissions配置。所有 action 均固定到稳定大版本复制进.github/workflows/即可跑通。导语每次 push 之后还要手动跑npm install、build、test再敲一串命令发版——这是很多前端/Node 同学每天的重复劳动。更糟的是测试只在自己机器上跑过合并到 CI 却因为环境不一致翻车排查半天发现是别人机器上的 Node 版本和你不一样。CI/CD持续集成 / 持续交付Continuous Integration / Continuous Delivery就是把这些重复的「构建、测试、发布」动作交给机器自动完成你只管推代码流水线在后台帮你验证、打包、发布。GitHub Actions是 GitHub 原生提供的事件驱动型 CI/CD 工作流引擎和仓库深度集成配置即代码一个 YAML 文件搞定。本文的目标是带你从 0 到 1 搭出一条能真正上线的流水线而不是只贴几个零散片段。关于缓存加速与矩阵测试的更多中文实战拆解也可以参考这篇 CSDN 文章GitHub Actions 自动化运维实战从零到一构建高效 CI/CD 流水线。声明本文基于个人使用体验非商业推广。一、为什么需要 CI/CD把重复的构建/测试/发布交给机器先说清楚痛点在哪。手工交付的典型循环是推代码 → 等自己或别人部署 → 出 bug → 回滚 → 再推。这个过程耗时长、易遗漏而且「能跑在我机器上」不等于「能在 CI 上跑」。自动化之后每次 push 都会自动触发测试与构建问题在合并前就被拦截发布也从「手动敲命令」变成「打一个 Release 就自动出包」。下面的对比表能直观看出差异维度手工交付GitHub Actions 自动化触发方式人工记得跑命令push / PR / Release 事件自动触发环境一致性依赖本机环境易漂移Runner 固定镜像结果可复现多版本测试手动切 Node 版本逐一跑matrix 一次并行跑 18/20/22发布手敲 npm publish易忘 tokenRelease 事件自动发版失败回滚靠人反应流水线失败即阻断合并GitHub Actions 的核心抽象是Workflow → Job → Step三层结构Workflow是一份 YAML 流程定义Job是互相独立或依赖的任务运行在Runner执行机上Step是 Job 里的一条条具体动作。它们的关系用一张文字流程图表示Event(例如 push / pull_request) │ ▼ Workflow(.github/workflows/*.yml) │ ├─ Job A runs-on: ubuntu-latest │ ├─ Step 1: uses actions/checkoutv4 # 拉代码 │ └─ Step 2: run npm ci # 装依赖 │ └─ Job B needs: Job A # 等 A 完成 └─ Step: run npm test # 跑测试 ▲ 由 Runner(执行机) 真正执行本文最终要落地的流水线就是push 触发 → checkout → 带缓存装依赖 → build → 多版本 test → 发布 npm/Docker。二、30 秒看懂核心概念与目录约定动手前先记住几条约定能省掉后面 80% 的报错。Workflow 文件必须放在仓库的.github/workflows/目录下扩展名是.yml或.yaml。一个最小的 Workflow 顶层包含这些键name工作流名、on触发事件push、pull_request、workflow_dispatch 等、jobs任务映射、env全局环境变量、defaults默认 run 配置。Job 级别的关键键有runs-on运行器标签、steps步骤序列、needs依赖其他 Job、strategy矩阵、env、secrets。Step 级别则是uses引用一个 action、run执行 shell 命令、with给 action 传参、name、env。Runner就是执行机分两类GitHub 托管运行器ubuntu-latest/windows-latest/macos-latest开箱即用自托管运行器则用标签[self-hosted, linux, x64]声明。下面这张速查表把几个核心概念并排对照概念是什么典型写法Workflow一份流程 YAML.github/workflows/ci.ymlJob一个任务跑在一台 Runner 上build:/test:StepJob 里的一步uses:或run:Runner真正执行命令的机器runs-on: ubuntu-latestAction可复用的封装单元actions/checkoutv4Event触发工作流的事情on: [push, pull_request]先看一个最小 Hello World建立整体结构感# .github/workflows/hello.yml —— 最小可用结构示意 name: Hello on: [push] # push 事件触发 jobs: greet: runs-on: ubuntu-latest # 用 GitHub 托管的 Ubuntu Runner steps: - name: Say hello run: echo Hello from GitHub Actions # 直接执行 shell三、实战一给 Node.js 项目搭一条最小可用 CI 流水线理解了结构先来一条「能跑起来」的最小 CI代码拉取 → 装依赖 → 构建 → 测试。绝大多数 workflow 的第一步都是actions/checkoutv4它负责把仓库代码拉到 Runner 上。装 Node 用actions/setup-nodev4有一个很实用的参数cache: npm它能一键启用 npm 依赖缓存等价于你手动写actions/cache但代码更少。关键点是CI 里要用npm ci而不是npm install——npm ci严格依据package-lock.json安装保证 CI 与本地依赖树一致、更快、更可复现。下面这条 workflow 是完整可运行的直接复制进.github/workflows/ci.yml即可# .github/workflows/ci.yml —— Node.js 最小 CIcheckout → 缓存 → build → test name: Node.js CI on: push: branches: [main] # 只在 main 分支的 push 上触发 pull_request: branches: [main] # PR 也触发合并前拦截问题 jobs: build-and-test: runs-on: ubuntu-latest steps: - name: 拉取代码 uses: actions/checkoutv4 # 固定到稳定大版本 v4 - name: 安装 Node 并开启 npm 缓存 uses: actions/setup-nodev4 with: node-version: 20 cache: npm # 自动缓存 ~/.npm命中即跳过下载 - name: 安装依赖锁定 lock 文件可复现 run: npm ci - name: 构建 run: npm run build - name: 运行测试 run: npm test缓存的命中逻辑是key 由runner.os加hashFiles(**/package-lock.json)生成只有依赖文件变化时才重建缓存命中时actions/cache会输出cache-hittrue。这正是setup-node的cache: npm在背后做的事你不用手写restore-keys回退。四、实战二多 Job 流水线 矩阵构建并行多版本测试一条「能跑」的 CI 还不够。真实项目往往要验证 Node 18 / 20 / 22 三个版本的兼容性——总不能手动切版本跑三遍。strategy.matrix就是为此设计的你声明一组变量数组GitHub Actions 会自动把它们展开成多个并行 Job。用needs可以串联 Job让build先跑test等它完成再跑前序失败后续不执行。矩阵里每个版本通过${{ matrix.node-version }}在 step 中引用。如果希望「一个版本挂了其他继续跑」把fail-fast设为false即可max-parallel则限制并发数避免一次性开太多机器。# .github/workflows/matrix.yml —— 多 Job 矩阵build 一次test 并行多版本 name: Matrix CI on: [push, pull_request] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm run build # 把构建产物留给后面的 test / deploy下一节用 Artifact 传递 test: needs: build # 必须等 build 成功 runs-on: ubuntu-latest strategy: fail-fast: false # 某个版本失败其余继续跑 max-parallel: 3 # 最多并行 3 个 Job matrix: node-version: [18, 20, 22] # 三个 Node 版本自动展开 steps: - uses: actions/checkoutv4 - name: 安装 Node ${{ matrix.node-version }} uses: actions/setup-nodev4 with: node-version: ${{ matrix.node-version }} cache: npm - run: npm ci - run: npm test上面的配置会展开成3 版本 × 1 OS 3 个并行 test Job而build只跑一次。这就是流水线「构建一次、测试复用」的基本思路也为下一节的产物传递埋下伏笔。五、实战三用 Artifacts 在 Job 之间传递产物build打出来的dist/目录怎么安全交给deployJob答案是Artifacts构件actions/upload-artifactv4上传文件actions/download-artifactv4在下游 Job 下载。注意两点下载方必须用needs建立依赖且name要和上传时一致。一个容易踩的坑v4 起 Artifact不可变同一 workflow 内复用要换不同name比如dist-v1。Artifacts 和缓存cache职责不同下面这张表说清区别对比项缓存 actions/cache构件 Artifacts主要用途加速依赖安装跨 Job / 运行留存构建产物命中范围同分支、同 key 命中整个 workflow 内可下载是否可下载否仅 Runner 内是在 Actions UI 下载典型场景缓存 node_modules传递 dist/、测试报告# .github/workflows/artifact.yml —— build 上传 distdeploy 下载后部署 name: Artifact Demo on: [push] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - run: npm run build - name: 上传构建产物 uses: actions/upload-artifactv4 with: name: dist # 上传名 path: dist/ # 要传递的目录 retention-days: 7 # 自定义保留天数不超组织上限 deploy: needs: build # 依赖 build确保产物已上传 runs-on: ubuntu-latest steps: - name: 下载构建产物 uses: actions/download-artifactv4 with: name: dist # 必须与上传 name 一致 path: dist/ - name: 部署示例列出产物 run: ls -la dist/六、实战四自动发布——npm 包 / Docker 镜像构建测试都通过后发布也该自动化。发布要「只在打 Release 时触发」避免误发所以用on: release: types: [published]。发布 npm 包的关键三步setup-node设registry-url把仓库 SecretNPM_TOKEN注入环境变量NODE_AUTH_TOKEN再npm publish。注意变量名必须是NODE_AUTH_TOKENnpm 客户端会读取它做鉴权。# .github/workflows/publish-npm.yml —— 发布到 npm仅 Release 触发 name: Publish to npm on: release: types: [published] # 只在发布 Release 时发版 jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-nodev4 with: node-version: 20 registry-url: https://registry.npmjs.org - run: npm ci - run: npm publish env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} # 仓库 Secret绝不写进 YAML如果要推 Docker 镜像到 GitHub 容器 registryghcr.io用docker/login-action登录username填${{ github.actor }}password用内置的${{ secrets.GITHUB_TOKEN }}再借助docker/build-push-action设push: true。这里务必在 job 级声明permissions: packages: write否则默认令牌无权推送。# .github/workflows/publish-docker.yml —— 推送镜像到 ghcr.io name: Publish Docker on: release: types: [published] jobs: docker: runs-on: ubuntu-latest permissions: packages: write # 推送 ghcr 必需 contents: read steps: - uses: actions/checkoutv4 - name: 登录 ghcr.io uses: docker/login-actionv3 with: registry: ghcr.io username: ${{ github.actor }} password: ${{ secrets.GITHUB_TOKEN }} - name: 构建并推送镜像 uses: docker/build-push-actionv6 with: context: . push: true tags: ghcr.io/${{ github.repository }}:${{ github.sha }}七、Secrets 与权限安全管理 Token敏感信息一律放进Repository Secrets路径Settings → Secrets and variables → Actions在 YAML 里只通过${{ secrets.NAME }}引用绝不以明文写出。GITHUB_TOKEN是每次 Job 自动注入的内置 Secret作用域仅限于当前仓库——它很方便但默认权限可能过宽发布场景要像上一节那样显式提升packages权限。一个官方文档明确警告的坑缓存路径里不要存 token / 密码。任何能发起 PR 的人都可能通过缓存的读取机制拿到其中的内容。更安全的做法是优先用OIDCid-token: write做云厂商的免密钥登录避免长期凭证泄露。场景推荐做法npm token存 Secret注入NODE_AUTH_TOKEN云厂商登录用 OIDC 临时凭证而非长期 AK/SK跨 Job 传文件Artifacts不塞进缓存默认令牌job 级显式声明最小 permissions八、最佳实践与避坑指南把前面几节串起来后再补几条能少踩坑的经验。第一固定 action 大版本写actions/checkoutv4而非main或latest防止上游更新让你的流水线突然失败。第二托管 Runner 适合公共项目免费使用重度 / 私有构建可上自托管省成本。第三控制成本与时长开缓存、fail-fast、用concurrency取消过期的重复运行、给 Job 设timeout-minutes。常见翻车点 Top 清单Secrets 没配置 → 发布直接 403permissions缺失 →GITHUB_TOKEN无权推 ghcrNode 版本漂移 → 本地 20、CI 18行为不一致Windows / Linux 路径与换行差异 → 脚本在 macOS 跑得好好的到 Windows Runner 报错npm install代替npm ci→ 依赖树不锁定偶发诡异 bugArtifactname上下不一致 → 下载为空缓存里误存 token → 潜在泄露忘了needs→ 下游 Job 在产物还没上传时就启动。# 超时与并发控制示例避免堆积与无限运行 concurrency: group: ci-${{ github.ref }} # 同分支同一时间只跑一个 cancel-in-progress: true # 新 push 取消旧运行 jobs: build: runs-on: ubuntu-latest timeout-minutes: 15 # 单 Job 超时保护九、总结一条流水线打通构建、测试与发布回顾全链路push → checkout → 缓存依赖 → build → 矩阵 test → Artifact 传递 → 发布 npm / Docker。本文给出的每一段 YAML 都固定了稳定大版本复制进.github/workflows/就能直接跑通跑完即具备上线能力。需要强调的是CI/CD 不是「配一次就完事」它是随项目演进持续打磨的。下一步可以探索的方向有用Environments做发布审批门禁、把重复逻辑抽成Composite Action复用、用Dependabot自动升级 action 与依赖版本以保障安全。把机械的重复交给机器你只需专注写出更好的代码。参考资料GitHub Docs - Workflow syntax for GitHub Actionshttps://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actionsGitHub Docs - Store and share data with workflow artifactshttps://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifactsGitHub Docs - Running variations of jobsmatrix strategyGitHub Docs - Dependency caching referenceactions/cacheGitHub Docs - Publishing Node.js packages / Publishing Docker imagesGitHub Container RegistryCSDN - GitHub Actions 自动化运维实战中文补充阅读见正文导语内链© 2024 | 转载请注明出处结论PASS
