一、为什么迁移到 GitHub Actions无需额外服务器GitHub 原生集成免费额度充足2000 分钟/月矩阵构建一次 push 测试多个 Node 版本、多个操作系统生态丰富官方 marketplace 有上万 actions配置即代码.github/workflows/*.yml随仓库版本管理迁移前Jenkins 自建服务器维护成本高构建不稳定。迁移后所有流程自动化PR 自动跑测试主干自动部署。二、5 个踩过的坑与解决方案坑 1权限不足导致 actions 无法触发现象pull_request事件中从 fork 仓库提交的 PR 无法访问 secrets。原因GitHub 出于安全考虑fork PR 默认不传递 secrets。解决使用pull_request_target事件注意安全风险需谨慎。on:pull_request_target:branches:[main]坑 2缓存失效每次依赖安装 3 分钟错误做法每次跑npm ci都不缓存。正确做法使用actions/cache缓存node_modules。-name:Cache node_modulesuses:actions/cachev4with:path:~/.npmkey:${{runner.os}}-node-${{hashFiles(package-lock.json)}}restore-keys:|${{ runner.os }}-node-坑 3矩阵策略导致重复构建需求需要在 Node 18、20、22 上分别测试但每次 push 都跑 3 次浪费时间。解决使用矩阵但限定只在push到 main 或schedule时跑多版本PR 只跑最新版。strategy:matrix:node-version:[18.x,20.x,22.x]# 只在 main 分支跑全部exclude:-node-version:18.xif:github.ref!refs/heads/main坑 4环境变量在 composite action 中不生效现象自定义 action 里读取不到env上下文。解决通过with参数显式传递或使用${{ env.MY_VAR }}语法。坑 5workflow 复用导致调试困难问题多个项目共用同一个 workflow出错时难以定位。解决使用可复用 workflow (workflow_call)并增加workflow_dispatch手动触发调试。on:workflow_call:inputs:environment:required:truetype:stringsecrets:DEPLOY_KEY:required:true三、完整 workflow 模板可直接复制示例Node.js 项目 CI 自动部署到 Vercelname:CI/CDon:push:branches:[main,develop]pull_request:branches:[main]jobs:test:runs-on:ubuntu-lateststrategy:matrix:node-version:[18.x,20.x]steps:-uses:actions/checkoutv4-uses:actions/setup-nodev4with:node-version:${{matrix.node-version}}cache:npm-run:npm ci-run:npm testdeploy:needs:testif:github.ref refs/heads/mainruns-on:ubuntu-lateststeps:-uses:actions/checkoutv4-name:Deploy to Verceluses:amondnet/vercel-actionv20with:vercel-token:${{secrets.VERCEL_TOKEN}}vercel-org-id:${{secrets.VERCEL_ORG_ID}}vercel-project-id:${{secrets.VERCEL_PROJECT_ID}}vercel-args:--prod四、常用 actions 清单用途Action缓存依赖actions/cachev4设置 Nodeactions/setup-nodev4设置 Pythonactions/setup-pythonv5上传 artifactactions/upload-artifactv4下载 artifactactions/download-artifactv4发送 Slack 通知slackapi/slack-github-actionv1部署到云服务器easingthemes/ssh-deploymain五、总结GitHub Actions 完全取代 Jenkins 等传统 CI配置即代码免费额度足够中小项目。重点注意缓存策略、权限处理、矩阵优化、workflow 复用。文中的所有 workflow 代码均可直接复制使用根据项目调整即可。建议收藏本文下次新项目搭建 CI 时直接抄配置。下一篇写“GitHub Actions 安全最佳实践”。