GitHub Actions CI/CD流水线配置教程：从代码提交到自动测试部署的实战脚本

开场：OK，今天直接把“手动发版”干掉

哈喽兄弟们，eccfy上镜！今天我们不聊虚的，直接上手搭一条真正能跑的 GitHub Actions CI/CD 流水线。你会看到我从 push 代码 开始，自动跑测试、打包、再到部署，一条龙走完。这个教程适合你搜“GitHub Actions CI/CD流水线配置教程”“GitHub Actions怎么用”“GitHub Actions部署教程”的时候直接拿来抄。

OK so，先说结论：如果你项目还在靠人肉执行 npm test、手动打包、FTP 上传，那这套流程能立刻把重复劳动砍掉。我自己在一个 Node.js 项目里测过，CI 从 3 分 40 秒缩到 1 分 52 秒，主要优化点就是缓存依赖和并行测试。接下来我边讲边给你看配置。

第一章：先搭最小可用 CI，别一上来就整复杂

屏幕打开仓库，接下来在项目里新建 .github/workflows/ci.yml。先做最小闭环：安装依赖、跑测试、失败就阻断。这个阶段先别急着部署，先确认“代码提交后自动验证”是真的通的。

直接看 YAML：

name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install
        run: npm ci

      - name: Test
        run: npm test

这里有三个关键点。第一，npm ci 比 npm install 更适合 CI，锁定版本更稳定。第二，cache: 'npm' 会缓存依赖，实际测试里通常能省 20%~40% 时间。第三，pull_request 一定要开，不然别人提 PR 你根本不知道会不会炸。

如果你是搜“GitHub Actions教程”“GitHub Actions自动部署前置配置”的人，先把这一步跑通，再往下走。别跳步骤，真的。

第二章：接上构建和部署，Now watch this

接下来上部署。假设你是把前端构建产物丢到服务器，或者发到对象存储，都可以走同一个思路：先 build，再把产物传出去。先给你一个通用版本，适合静态站或前端项目。

name: Deploy

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    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 run build

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist

如果你要直连服务器，通常会再加 appleboy/scp-action 或 SSH 命令。比如把 dist/ 上传到 Nginx 目录，或者重启服务。重点不是工具名，而是流程：先构建成功，再部署，不要把部署失败归因到构建失败，排查要分层。

我在一个 2 核 4G 的 VPS 上测试过，前端项目 build 约 48 秒，上传 18 秒，整条流水线 1 分 20 秒左右。你要是发现突然变成 5 分钟，先看是不是缓存失效、依赖下载变慢，或者 runner 区域波动。

第三章：常见翻车点，直接给你排查清单

OK，下面是最容易翻车的地方。你照着看，基本能少掉一半时间。

权限问题：部署用的 Secret 没配好，去仓库 Settings → Secrets and variables 检查。
分支触发错了：main/develop 写反，导致 workflow 根本不跑。
Node 版本不一致：本地能跑，CI 挂掉，优先统一 node-version。
构建产物路径错：dist、build、out 经常写混。
缓存污染：依赖改了但缓存没更新，先临时关缓存验证。

给你一个我常用的判断方法：如果测试挂在“安装依赖”，问题通常是锁文件或镜像；如果挂在“构建”，多半是环境变量缺失；如果挂在“部署”，优先查 SSH key、服务器目录权限、目标端口是否开放。

怎么验证它真的好了？三步：1）提交一个故意写错的测试，看 CI 是否拦住；2）修正后再提交，确认 workflow 变绿；3）检查部署目标是否收到最新文件，页面刷新后版本号变化。这样就不是“感觉成功”，而是实打实验证成功。

结尾：你现在就能抄的最小方案

如果你现在只想快速上线，我建议先用官方内置能力：GitHub Actions + cache + artifact，免费方案足够覆盖大多数中小项目。要是后面你想把自托管 runner、灰度发布、SSH 自动部署也接上，再继续扩展就行。最后如果你想我下一期继续拆“GitHub Actions 自动部署到服务器”的完整脚本，评论区告诉我，eccfy 直接给你写成可复制版本。