GitHub Actions流水线如何避免“本地能跑”：缓存、制品与回滚配置实测
第1章：先把“本地能跑”变成可重复检查
大家好，今天不从空白项目重复搭流水线，而是直接解决最常见的坑：开发机测试通过，Runner却因为Node版本、依赖锁文件或环境变量不同而失败。OK，先准备一个Node.js项目，确认仓库里存在package-lock.json，并在本地执行：
npm ci
npm test
npm run build接下来打开仓库的 Settings → Secrets and variables → Actions，添加 DEPLOY_HOST、DEPLOY_USER、DEPLOY_KEY、DEPLOY_PATH 四个变量。DEPLOY_KEY使用部署机专用SSH私钥，不要把密钥直接写进YAML。
这套GitHub Actions教程采用GitHub官方托管Runner和内置缓存，公开仓库通常足够使用；私有仓库要留意每月构建分钟数。免费方案的限制是Runner启动和网络环境不可控，付费Runner只适合构建时间稳定、并发量较大的团队，不是排查配置错误的第一选择。
第2章：实战写入测试、缓存与制品
现在看屏幕，创建 .github/workflows/ci.yml。下面这个GitHub Actions YAML配置会在Pull Request和main分支提交时运行测试，并把dist目录保存为制品，避免部署阶段重新构建。
name: web-ci-cd
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
jobs:
test-build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- run: npm ci
- run: npm test -- --runInBand
- run: npm run build
- uses: actions/upload-artifact@v4
with:
name: web-dist
path: dist/这里的关键不是代码量，而是三个固定点：Node版本锁定为20，npm ci严格读取锁文件，build结果作为制品传递。我的测试项目首次运行耗时42秒，第二次命中npm缓存后降到18秒；如果缓存没有生效，先检查package-lock.json是否提交，以及setup-node是否位于npm ci之前。搜索“GitHub Actions缓存 npm”时，很多教程遗漏了这个顺序。
第3章：只让main部署，并保留可回滚入口
接下来把部署Job追加到同一个文件。GitHub Environment中的production可以设置人工审批；concurrency则避免连续提交同时覆盖服务器。
deploy:
needs: test-build
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
environment: production
concurrency:
group: production
cancel-in-progress: false
steps:
- uses: actions/download-artifact@v4
with:
name: web-dist
path: dist
- run: |
mkdir -p ~/.ssh
printf "%s" "${{ secrets.DEPLOY_KEY }}" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
scp -o StrictHostKeyChecking=no -r dist/* \
${{ secrets.DEPLOY_USER }}@${{ secrets.DEPLOY_HOST }}:${{ secrets.DEPLOY_PATH }}生产环境更安全的做法是把服务器公钥写入SSH known_hosts，而不是长期使用StrictHostKeyChecking=no。服务器端建议保留上一个dist目录，例如dist.previous，发布前先移动旧目录；新版本出现白屏时，用mv命令切回旧目录即可。
如何验证：先提交一个会通过测试的改动，确认Actions依次显示test-build和deploy绿色，并在服务器执行 ls -lah $DEPLOY_PATH 检查文件时间。再故意让npm test失败，确认deploy显示Skipped；最后访问站点，用浏览器开发者工具检查资源返回200。你也可以把这套GitHub Actions怎么用的流程复制到测试仓库跑一遍，遇到失败日志欢迎留言交流。