GitHub Actions 部署工作流:配置详解与踩坑复盘

手动部署的三条命令

这个博客是 Hexo 静态站,部署链路很短:本地生成 public/ 目录,再把它同步到服务器上 Nginx 的站点根目录. 手动做一遍就是三条命令:

pnpm install
npx hexo generate
rsync -avz --delete public/ ubuntu@<server-ip>:/home/ubuntu/workspace/blog-hexo/public/

命令不多,问题在于每写一篇文章都要重复一遍,而且它绑在某台特定机器上:

• 换电脑要重新配 SSH 密钥和 Node 环境
• 忘了 hexo generate 就会把旧内容同步上去,而且不会有任何报错
• rsync 路径手滑打错,配上 --delete 足以删掉服务器上不该删的目录

CI 要解决的就是这类问题:把"人得记着做的步骤"变成"仓库里写死的步骤",由事件自动触发,在一个每次都一样的环境里执行.

Workflow 的层级结构

GitHub Actions 的配置有四层,从外到内嵌套. 先建立这个骨架,后面每个字段都是往这个骨架里填东西:

Event  push 到 main 分支
  │
  ▼
Workflow  .github/workflows/deploy.yml
  │
  ▼
Job  deploy  ← 一台全新的 ubuntu 虚拟机
  │
  ├─▶ Step 1  检出代码
  ├─▶ Step 2  装 pnpm
  ├─▶ Step 3  装 Node
  ├─▶ Step 4  装依赖
  ├─▶ Step 5  生成静态文件
  └─▶ Step 6  同步到服务器

四层模型的通用部分在云原生分类的 GitHub Actions 实战一篇里讲过,这里不重复,直接落到一个真实文件上逐字段拆.

字段逐个拆

on:什么时候跑

on 决定触发条件,是整个文件里唯一和"时机"有关的部分:

on:
  push:
    branches: [main]        # 只有推送到 main 才触发,推 feature 分支不触发
  pull_request:
    branches: [main]        # 针对 main 的 PR 也触发一次
  schedule:
    - cron: "0 2 * * *"     # 每天 02:00 UTC 定时跑
  workflow_dispatch:        # 在 Actions 页面手动点按钮触发

部署类 workflow 通常只监听 push 到主干. 加上 pull_request 意味着别人提 PR 就会触发部署,这显然不合理——PR 阶段该跑的是测试,不是部署.

jobs 与 runs-on:在哪儿跑

jobs:
  deploy:                   # 这一层的 key 是 Job 的 id,自己起名
    runs-on: ubuntu-latest  # 用 GitHub 托管的 Ubuntu 虚拟机
    steps: ...

runs-on 常用值是 ubuntu-latest,macos-latest,windows-latest. 需要访问内网或特定硬件时可以挂自托管 Runner,但要自己负责机器的安全和维护.

多个 Job 默认并行. 需要串行时用 needs 声明依赖:

jobs:
  test:
    runs-on: ubuntu-latest
    steps: [...]

  deploy:
    needs: test             # test 成功才开始;test 失败则 deploy 直接跳过
    runs-on: ubuntu-latest
    steps: [...]

steps:跑什么

Step 只有两种写法,uses 和 run:

steps:
  - uses: actions/checkout@v4      # 复用别人写好的 Action,@v4 是版本

  - uses: actions/setup-node@v4
    with:                          # with 给 Action 传参数
      node-version: "24"

  - name: Deploy to server         # name 是显示在日志里的步骤名,可选
    env:                           # env 给这一步注入环境变量
      DEPLOY_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
    run: |                         # run 直接执行 shell,| 表示多行
      echo "$DEPLOY_KEY" > key

${{ ... }} 是表达式语法,用来引用上下文变量. 常用的几个上下文:secrets.X 取仓库密钥,github.ref 取当前分支,matrix.X 取矩阵变量,inputs.X 取手动触发时填的参数.

这个博客的完整 workflow

把上面的字段拼起来,就是仓库里 .github/workflows/deploy.yml 的全部内容:

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4          # 把仓库代码检出到 Runner

      # 不写 version,pnpm 版本由 package.json 的 packageManager 字段决定
      - uses: pnpm/action-setup@v4

      - uses: actions/setup-node@v4
        with:
          node-version-file: ".nvmrc"      # Node 版本由 .nvmrc 决定
          cache: "pnpm"                    # 按 lockfile 哈希缓存 pnpm store

      - run: pnpm install --frozen-lockfile

      - run: npx hexo generate             # 产出 public/ 目录

      - name: Deploy to server
        env:
          DEPLOY_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
        run: |
          mkdir -p ~/.ssh
          echo "$DEPLOY_KEY" > ~/.ssh/id_ed25519
          chmod 600 ~/.ssh/id_ed25519
          ssh-keyscan -H <server-ip> >> ~/.ssh/known_hosts
          rsync -avz --delete \
            -e "ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes -o BatchMode=yes" \
            public/ ubuntu@<server-ip>:/home/ubuntu/workspace/blog-hexo/public/

这份文件里没有出现任何 pnpm 或 Node 的版本号. 两个版本都由仓库里的另外两个文件决定:package.json 的 packageManager 字段和 .nvmrc. 这么做的收益不在 CI 而在本地——corepack 和 nvm 读的是同样这两个文件,本地和 Runner 因此必然跑在同一套工具链上. 后面复盘的第一个故障,根源就是这两边的版本不一致.

有两处顺序不能调换.

pnpm 必须装在 setup-node 之前. setup-node 的 cache: "pnpm" 要靠执行 pnpm store path 来定位缓存目录,如果这时系统里还没有 pnpm,这一步会直接失败. 这是"声明式配置里藏着隐式依赖"的典型例子,YAML 的缩进结构完全看不出这层关系.

--frozen-lockfile 必须在 generate 之前,并且不能省. 它的作用是:lockfile 和 package.json 不一致时直接报错,而不是自作主张更新 lockfile. CI 的价值就在于确定性,依赖版本必须完全由提交进仓库的 lockfile 决定.

私钥是怎么进到 Runner 里的

部署那一步的四行命令,每行都在解决 SSH 的一个具体要求:

mkdir -p ~/.ssh                                  # Runner 是新机器,这个目录不存在
echo "$DEPLOY_KEY" > ~/.ssh/id_ed25519           # 把 Secret 落成密钥文件
chmod 600 ~/.ssh/id_ed25519                      # ssh 拒绝使用权限过宽的私钥
ssh-keyscan -H <server-ip> >> ~/.ssh/known_hosts # 提前录入 host key,否则非交互下连接被拒

私钥的传递路径是 仓库 Secret → Step 的环境变量 → Runner 上的文件. 用 env 中转而不是在 run 里直接插值,是有讲究的:直接写 echo "${{ secrets.DEPLOY_SSH_KEY }}",私钥内容会被拼进 shell 命令行,私钥里的特殊字符可能破坏命令语法,命令本身也更容易出现在进程列表或调试输出里. 走环境变量则只有 shell 自己能读到.

Secret 在日志里会被自动替换成 ***,但这只是兜底:它按字面匹配,一旦密钥被 base64 编码或分行输出,打码就失效了.

踩坑复盘

配置写完不等于跑通. 下面两个故障有一个共同特征:本地完全正常,CI 稳定失败.

故障一:pnpm install 直接 exit 1

日志末尾是这样:

+ markdown-it-anchor 9.2.1
[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: hexo-util@3.3.0, hexo-util@4.0.0
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.
Error: Process completed with exit code 1.

依赖全都装完了,最后一步却报错退出. 报错说的是"忽略了 hexo-util 的构建脚本". pnpm 从 10 开始默认不执行依赖的 postinstall,这是防供应链攻击的措施,要放行得显式配置白名单. 而仓库里的 .npmrc 明明已经配了:

only-built-dependencies[]=hexo-util

本地 pnpm install 一切正常,CI 里这行配置像不存在一样. 关键线索藏在日志开头两行:

Verifying lockfile against supply-chain policies (192 entries)...
Content-addressable store is at: /home/runner/setup-pnpm/.../store/v11

store/v11 和 supply-chain 检查都是 pnpm 11 的特征,而本地装的是 10.33. workflow 里写的是 version: latest,于是 CI 装到了当时最新的 11.20.0. 一个大版本的差距,同时踩中了三个变更:

三条叠加的结果:白名单配置被静默忽略,而忽略构建的后果从警告升级成硬错误. 本地不报错,是因为 pnpm 10 两条都不成立.

顺带确认了这个 postinstall 不能跳过:hexo-util 的构建脚本会生成 highlight_alias.json,这个文件不在发布的 tarball 里,由安装时按实际的 highlight.js 版本现场生成. 跳过它,hexo 运行时会找不到模块. 所以只能放行,不能屏蔽.

止血的改法是新建 pnpm-workspace.yaml,把两个字段名并列写上:

onlyBuiltDependencies:   # pnpm 10 读这个
  - hexo-util

allowBuilds:             # pnpm 11 读这个
  hexo-util: true

两个版本各读自己认识的那个键,互相不认识的键被忽略且不报警,于是本地的 10 和 CI 的 11 都能跑. 同时把 .npmrc 删掉——在 pnpm 11 眼里那行配置已经没有意义,留着只会误导下一个读代码的人.

但这只是止血,真正的病根是本地和 CI 跑着两个大版本的 pnpm,而这件事在故障发生前没有任何人知道. 兼容两个版本的配置能让流水线变绿,却把"版本不一致"这个状态固化了下来,下一次大版本变更还会再撞一次.

根治的做法是消灭这个差异,让版本只有一个来源:

// package.json
{
  "packageManager": "pnpm@11.20.0"
}

// .nvmrc
24

packageManager 是 corepack 认的字段,本地敲 pnpm 时 corepack 会自动切到 11.20.0;pnpm/action-setup 在省略 version 输入时读的也是这个字段. .nvmrc 同理,本地被 nvm 读取,CI 里由 setup-node 的 node-version-file 读取. 两边从此不可能不一致.

版本统一之后,pnpm-workspace.yaml 里那份兼容写法就可以收掉,只留 pnpm 11 认的那一个键:

# hexo-util 的 postinstall 会生成 highlight_alias.json, 必须允许它执行.
allowBuilds:
  hexo-util: true

故障二:rsync 被服务器拒绝

依赖问题解决后,卡在最后一步:

Permission denied, please try again.
Permission denied, please try again.
ubuntu@<server-ip>: Permission denied (publickey,password).
rsync: connection unexpectedly closed (0 bytes received so far) [sender]
rsync error: unexplained error (code 255) at io.c(232) [sender=3.2.7]

这段日志的信息量比看起来大:

• Permission denied (publickey,password) 里的括号列出了服务器接受的认证方式,不是失败原因. 真正的信息是公钥认证没通过
• 两次 Permission denied, please try again. 是密码认证的重试提示. 公钥失败后 ssh 退回去试密码,CI 里没有人能输入密码,于是空跑两次
• 没有出现 Load key: error in libcrypto 之类的报错,说明私钥文件本身格式正确,能被解析

所以问题不在 Secret,而在服务器那边不认这把钥匙. 定位手法是指纹比对,ssh-keygen -lf 对私钥和公钥都能算出同一个指纹:

# 本地:算出 Secret 里那把私钥的指纹
ssh-keygen -lf ~/.ssh/github_actions_deploy
# 256 SHA256:yAr5ev... github-actions-deploy (ED25519)

# 服务器:列出所有已授权公钥的指纹
ssh-keygen -lf ~/.ssh/authorized_keys
# 3072 SHA256:6l9C5g... my-laptop (RSA)
# 256 SHA256:/vu4iq... github-actions-note-mine (ED25519)

指纹一比就清楚了:服务器上授权的是另一把旧密钥 github-actions-note-mine,Secret 里那把 github-actions-deploy 从来没被授权过. 密钥对本身没问题,漏的是"把公钥交给服务器"这一步.

修复就是追加公钥,注意两个细节:

f=~/.ssh/authorized_keys
# 末尾没有换行符时先补一个,否则新公钥会和上一行粘成一行,两把钥匙一起失效
[ -s $f ] && [ "$(tail -c1 $f | wc -l)" -eq 0 ] && echo >> $f
grep -qF "$PUB" $f || printf '%s\n' "$PUB" >> $f
chmod 600 $f

追加完之后要只用这把钥匙验证一次,否则本地 ~/.ssh/config 里的其他密钥会掩盖问题:

ssh -i ~/.ssh/github_actions_deploy -o IdentitiesOnly=yes -o BatchMode=yes \
    ubuntu@<server-ip> 'echo AUTH_OK'

IdentitiesOnly=yes 禁止 ssh 试其他密钥,BatchMode=yes 禁止一切交互提示. 这两个选项后来也加进了 workflow 的 rsync 命令里:

rsync -avz --delete \
  -e "ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes -o BatchMode=yes" \
  public/ ubuntu@<server-ip>:/path/to/public/

不加也能跑通,加了是为了让失败的样子更明确. 原本那两行莫名其妙的 Permission denied, please try again.,就是 ssh 悄悄降级去试密码的产物,读日志时很容易被带偏. 配上 BatchMode 后,公钥不通会立刻报错说清原因.

排错方法论:在本地复刻 CI 环境

上面两个故障都是"本地正常,CI 失败",这类问题几乎都是环境差异,而 CI 环境的三个特征是可以在本地复刻的:指定版本的运行时,干净的依赖目录,一模一样的命令.

# 拷一份仓库到临时目录,排除 node_modules 以模拟全新 Runner
rsync -a --exclude node_modules --exclude .git ./ /tmp/ci-repro/
cd /tmp/ci-repro

# 用 CI 里的 Node 和 pnpm 版本跑同样的命令
nvm use 24
npx pnpm@11.20.0 install --frozen-lockfile

这么做的收益很直接:一轮验证只要几秒,而 push 一次要等一分多钟;不会在 git 历史里留下一串 fix ci 提交;临时目录跑坏了随时删,不影响正在用的 node_modules.

修完之后别忘了验证部署真的落地了,而不是只看 Actions 页面变绿:

ssh <server> 'ls -l --time-style=+%Y-%m-%d_%H:%M /path/to/public/index.html'
# -rw-r--r-- 1 ubuntu ubuntu 5919 2026-08-06_11:26 .../index.html

rsync -a 会保留源端的修改时间,所以目标文件的 mtime 就是 CI 生成它的时刻. 这个时间对上了,才算真的部署成功.