GitHub Actions 发 npm 包:NPM_TOKEN 换成可信发布,工作流要改哪几处

29 阅读6分钟

🚀 省流助手

  • CI 不用过 2FA,也不用存 npm token:包设成发布必须 2FA 后,GitHub Actions 仍能靠可信发布(OIDC)自动发包,我实测通过。
  • 工作流必改 3 处:加 id-token: write、确保 npm ≥ 11.5.1、删掉 NODE_AUTH_TOKEN。用 Lerna 的还要升到 v9。
  • npm 这边每个包都要登记一次工作流文件名:npm trust github @your-org/pkg-a --repo your-org/your-repo --file publish.yml --allow-publish。
  • 只有 npm 的 token 能删。工作流推代码用的 GitHub token 不受影响。

一、先分清:换掉的是 token,2FA 还留在账号上

很多人卡在一个问题上:账号开了 2FA,CI 里又没人能输验证码,怎么发包?

答案是 CI 不走 2FA 这条路。可信发布让 npm 信任一个指定的工作流,发布时用 OIDC 换一个短期凭据,不需要长期 token。

发布方式怎么认证是否需要过 2FA
本地 npm publish账号登录需要
CI 用 NPM_TOKEN长期 token 存在 Secret 里看 token 类型和包设置
CI 用可信发布OIDC 换短期凭据不需要

所以这次改动分两边:工作流改 3 处,npm 上登记 1 次。

二、工作流要改的 3 处

下面这段 diff 就是改动的全部,其他步骤可以不动。

 jobs:
   publish:
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      id-token: write
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
           node-version: "22"
           registry-url: "https://registry.npmjs.org"
+      - run: npm install --global npm@11.21.1
       - run: npm ci
       - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

ⓐ 加 id-token: write

没有这个权限,工作流就拿不到 OIDC 令牌。npm 文档称它是 “The critical requirement”。

如果用 workflow_call 调用另一个工作流来发布,父子工作流都要给这个权限,而且 npm 校验的是调用方的工作流文件名,登记时别填错。

ⓑ 确保 npm 版本够

npm 文档的要求:

Trusted publishing requires npm CLI version 11.5.1 or later and Node version 22.14.0 or higher.

Node 自带的 npm 不一定够,查 Node 官方发布清单的结果如下:

Node 版本自带 npm是否满足
22.23.410.9.9不满足,要单独升级 npm
24.22.211.19.1满足

所以有两个选择:留在 Node 22 并加一步升级 npm,或者换到 Node 24。官方示例用的是 Node 24,没有升级 npm 这一步。

ⓒ 删掉 NODE_AUTH_TOKEN

把发布步骤里的 NODE_AUTH_TOKEN 删掉。setup-node 的 registry-url 我保留了,官方示例也保留。

--provenance 参数也可以不写,文档说明通过可信发布时默认生成。

三、npm 上要登记一次

工作流改完还不够,npm 得知道信任谁。

npm trust github @your-org/pkg-a \
  --repo your-org/your-repo \
  --file publish.yml \
  --allow-publish

也可以在网页上操作:包的 Settings → Trusted publishing。

要注意的点说明
--file只写文件名,带 .yml,不写路径。大小写要完全一致
--allow-publish2026-09-03 之后新建的配置默认只允许 npm stage publish,要直接 npm publish 必须加上
多包仓库每个包都要登记。工作流文件改名后,每个包都要重新配置
期限新配置要在 2 天内完成首次成功发布,否则过期,只能删除重建。我没有实测过期后的表现
新包文档写明 “The package you're configuring must already exist on the npm registry”,还没发过的包登记不了
2FA运行 npm trust 本身要过 2FA

四、哪些配置不用动

这几项容易被顺手改掉,其实和 npm 认证无关。

配置处理
工作流的触发条件不用改。我的工作流是 MR 合并触发,官方示例是 tag 触发,都可以
actions/checkout 用的 GitHub token不用改。工作流要推版本提交或 tag,仍然需要它
contents 权限不用改。要推代码就保持 write,官方示例只发包所以是 read
lerna.json 和版本规则不用改

五、用 Lerna 的话多两件事

Lerna 官方文档写明 OIDC 从 v9 开始支持:

In v9.0.0, Lerna added support for OIDC trusted publishing

所以 Lerna 要升到 9,文档说按 npm 的方式配置后不需要额外设置。我从 7.4.2 升到了 9.0.7,npm 版本和权限的要求同上。

还有一个我踩到的问题:在 9.0.7 上用一条 lerna publish 同时升版本和发布,并且内部依赖写的是 workspace: 时,发布出去的包依赖了旧版本。

版本提交中的依赖:workspace:0.0.8-alpha.0
发布后的依赖:0.0.7

我的解决办法是拆成两条命令,拆开后云端发布的依赖就对了:

npx lerna version --yes --no-push
npx lerna publish from-package --yes --dist-tag latest

六、怎么确认真的换过来了

发一个预发版,然后查 npm 上的发布者。

npm view @your-org/pkg-a@<version> _npmUser dist.attestations.provenance --json

我的真实输出:

{
  "_npmUser": "GitHub Actions <npm-oidc-no-reply@github.com>",
  "dist.attestations.provenance": {
    "predicateType": "https://slsa.dev/provenance/v1"
  }
}

_npmUser 是 GitHub Actions,说明走的是可信发布。provenance 只有公开仓库才有,私有仓库不生成,文档原文是 “Provenance generation is not supported for private repositories”,我私有仓库的 5 个包也确实没有。

确认没问题后,再做两步收尾:

  • 关掉 token 发布: 包的 Settings → Publishing access,选 “Require two-factor authentication and disallow tokens”。我在设了发布必须 2FA 的包上实测过,OIDC 发布仍然成功。
  • 清理旧 token: 删掉 GitHub 上的 NPM_TOKEN Secret 和 npm 账号里不用的 token。

七、换的时候容易遇到的问题

现象原因怎么办
OIDC 取令牌返回 200,发布却 E404我遇到的原因是可信发布者没登记成功(2FA 确认链接超时)。这时的 E404 不代表包不存在查包的登记结果,重新登记
ENEEDAUTH(Unable to authenticate)文档建议先查文件名是否完全一致,再查是否用了自托管 runner、是否有 id-token: write逐项核对
用了自托管 runner文档写明目前不支持换 GitHub 托管的 runner
npm ci 认证失败可信发布只管发布。装私有依赖还要给只读 token给安装步骤单独配 NODE_AUTH_TOKEN,用只读 token
账号突然不能发布和改设置用恢复码登录后,账号会只读 72 小时,到期自动解除。这是我自己遇到的,依据是 npm 2026-09-09 的公告配置要过 2FA 时别用恢复码

验证范围: 上面的配置在 5 个生产仓共 28 个包上真实发布过,另有 1 个试点仓,发布者、版本和 tag 都核对过。环境是 Node 22、npm 11.21.1、Lerna 9.0.7、pnpm,触发方式是 MR 合并;diff 里的 npm ci 和 npm publish 是按官方示例写的单包通用形式,我的实际命令是 Lerna。

参考: npm 可信发布文档、npm trust 命令、Lerna OIDC。