| name | actions-npm |
| description | Use when creating or debugging GitHub Actions workflows that publish npm packages with trusted publishing / OIDC. Triggers on npm publish in CI, ENEEDAUTH, E404 or E422 during publish, tag-triggered releases, setup-node auth behavior, or provenance issues in public vs private GitHub repositories. |
Actions NPM Publish (Trusted Publishing)
Workflow Template
See assets/release-npm.yml — 可直接复制到 .github/workflows/ 使用。
How It Works
trusted publishing 用 GitHub OIDC 替代长期有效的 NPM_TOKEN：
- workflow 运行在 GitHub-hosted runner 上
- job 具备
permissions.id-token: write
- npm /
actions/setup-node 用 GitHub OIDC 身份换取发布凭证
npm publish 使用该凭证发布
不需要 NPM_TOKEN secret。
Verified Requirements
- workflow 必须在
.github/workflows/
- 必须使用 GitHub-hosted runner
- 必须有
id-token: write
- npm trusted publisher 必须精确匹配仓库和 workflow 文件名，例如
release-auth-sdk.yml
package.json.repository.url 必须匹配 GitHub 仓库 URL- 推荐
actions/setup-node@v6
- 推荐 Node 24；如果保留 Node 22，需确认 npm 已升级到
11.5.1+
Important Gotchas
- 使用
actions/setup-node@v6 时，不要再手动设置 NODE_AUTH_TOKEN: ""。按实测，这种组合会导致 ENEEDAUTH；优先让 setup-node 自己处理发布凭证。
npm notice Publishing to https://registry.npmjs.org/ 之后再报 E404，通常说明认证已经通过，但 npm 侧的包权限、scope 权限，或 trusted publisher 元数据仍不匹配。E422 ... Unsupported GitHub Actions source repository visibility: "private" 表示 private GitHub 仓库不支持 --provenance。此时去掉 --provenance，保留普通 trusted publishing 即可。- provenance 目前只适用于 public source repository。
Publish Command
- public GitHub repo:
npm publish --provenance --access public
- private GitHub repo:
npm publish --access public
Quick Checklist
actions/setup-node@v6node-version: "24"registry-url: https://registry.npmjs.org/- 不配置
NPM_TOKEN
- 不手动覆盖
NODE_AUTH_TOKEN
- npm 后台 trusted publisher 中的 workflow filename 与实际文件名完全一致
