🚀 省流助手
- 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.4 | 10.9.9 | 不满足,要单独升级 npm |
| 24.22.2 | 11.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-publish | 2026-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_TOKENSecret 和 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。