SuperAPI AI 工具集

npm-trusted-publishing

部署与运维

查看项目

更新于 10-16 07:16

技能介绍

用途:从 GitHub Actions 发布 npm 包,不使用长期令牌。通过 OIDC 认证,并自动生成来源证明(provenance attestation)。

主要能力:GitHub Actions 在 tag 推送时触发工作流;工作流向 GitHub 请求短期 OIDC token;npm 用该 token 向 registry 换取发布 token;包在带来源证明的情况下发布,无需 NPM_TOKEN 密钥。

使用方式:

  1. 在 npmjs.org 对每个包一次性配置可信发布(Settings → Trusted publishing),Provider 选 GitHub Actions,组织/用户、仓库、工作流文件名需与 GitHub 完全一致且区分大小写;工作流文件名须为 publish.yml,除非使用 GitHub 部署环境否则不填 environment 名称。
  2. package.json 要求:repository.url 匹配 https://github.com/<user>/<repo>(不带 .git 后缀);包必须公开(私有包不能用 provenance);仓库必须公开。
  3. 工作流权限需 contents: read 与 id-token: write;使用 actions/checkout@v4 与 actions/setup-node@v4,registry-url 设为 https://registry.npmjs.org;发布命令为 npm publish --access public --provenance。

Node 版本:18.x/20.x(npm 9/10)不支持可信发布;22.x 需用 npx npm@11 publish;24.x、26.x(npm 11)可直接使用。

Monorepo:对每个可发布包用 working-directory 指定目录后分别执行发布命令。

验证:可用 npm view @scope/package version 确认版本,npm view @scope/package dist.attestations.provenance 确认来源证明,或在包页面查看 Provenance 徽章。

常见错误:ENEEDAUTH 通常是 setup-node 缺少 registry-url;404 多因 npm 10.x 搭配可信发布,改用 Node 24+ 或 npx npm@11 publish;403 为可信发布者配置不匹配,需检查区分大小写的组织/仓库/工作流;EPUBLISHCONFLICT 表示版本已存在。

限制:仅公开包与公开仓库可生成 provenance;npm 保存配置时不做校验,必须精确匹配。切勿提交含认证令牌的 .npmrc,切勿在工作流中使用 secrets.NPM_TOKEN 或长期发布令牌。

资料未提供收费与价格信息。