使用 Trusted Publishing 提升 npm 包发布安全性

在现代前端生态中，npm 包发布流程的安全性越来越重要。

传统的发布方式通常依赖长期有效的 npm token，一旦泄露，攻击者就可以直接发布恶意版本，带来严重的供应链风险。为了解决这一问题，npm 在 2025 年 7 月份推出了 Trusted Publishing（可信发布） 机制。

什么是 Trusted Publishing？

Trusted Publishing 是 npm 已正式推出基于 OpenID Connect (OIDC) 的可信发布功能。该功能允许使用 OpenID Connect (OIDC) 进行身份验证，直接从 CI/CD 工作流安全地发布 npm 包，从而减少管理长期令牌的需求。

借助可信发布，现在可以

• 无长期 token：不需要在仓库中保存 npm token
• 消除令牌安全风险：无需在 CI/CD 环境中存储、轮换或意外暴露 npm token。
• 短期凭证：每次发布时动态签发，自动过期
• 绑定 CI 身份，建立加密信任：发布权限与 GitHub 仓库/工作流强绑定，每次发布都使用短期、特定于工作流的凭据进行身份验证，这些凭据无法被泄露或重复使用。
• 降低泄露风险：即使 CI 配置泄露，也难以滥用
• 自动获取来源证明：使用可信发布时，npm CLI 默认发布来源证明。--provenance不再需要该标志。

传统发布方式的问题

在 Trusted Publishing 出现之前，常见流程如下：

1. 在 npm 上生成一个 Access Token
2. 将 token 存入 GitHub Secrets（如 NPM_TOKEN）
3. 在 CI 中执行 npm publish 进行发布

问题在于 token 通常是长期有效，一旦泄露，攻击者可以进行发布恶意版本等操作。

现在 npm 限制生成 token 最长有效期为 90 天，还使用这种方式会经常需要轮换 token。

Trusted Publishing 的工作原理

Trusted Publishing 会在 npm 和你的 CI/CD 提供商之间建立信任关系[1]。

当你为你的包配置可信发布者后，npm 将只接受来自你已授权的特定工作流的发布。

Trusted Publishing 基于以下流程：

1. GitHub Actions 在运行时向 npm 发起身份请求（OIDC）
2. npm 验证该请求是否来自可信仓库
3. 如果匹配配置，签发一个短期访问令牌
4. CI 使用该令牌执行 npm publish

整个过程：

• 无需手动管理 token
• 每次发布都是一次“临时授权”

设置 Trusted Publishing

我也是在发布 docsify-footnotes[2] 时发现 token 不可用了，此处以它为例：

1. npm 侧配置

进入 npm 包的 Settings页面，就可以看到Trusted Publisher，并且需要选择publisher，支持GitHub Actions、GitLab CI/CD 和CircleCI。

我的仓库在 GitHub，所以选择GitHub Actions，需要配置Organization or user、Repository和Workflow filename，这三个都是必填项。

GitHub 用户名或组织名称 Organization or user：sy-records仓库名称 Repository：docsify-footnotes工作流文件名 Workflow filename：publish.yml

点击Set up connection保存即可

2. GitHub Actions 配置

保存之后需要修改对应的 action yml 文件，需要将所需的 OIDC 权限添加到你的工作流中：

permissions:  id-token: write # Required for OIDC  contents: read 

关键要求是id-token: write需要获得相应的权限，才能让 GitHub Actions 生成 OIDC 令牌，这是一个完整例子：

name: PublishPackage  on: push:  tags:  -'v*'  permissions: id-token:write # Required for OIDC contents:read  jobs: publish:  runs-on:ubuntu-latest  steps:  -uses:actions/checkout@v6   -uses:actions/setup-node@v6  with:  node-version:'24'  registry-url:'https://registry.npmjs.org'  -run:npmci  -run:npmrunbuild--if-present  -run:npmtest  -run:npmpublish 

因为我的几个 npm 仓库都采用的 复用 actions[3]，所以只需要修改加上permissions和移除写入 npm token 就可以使用了，见 commit[4]。

发布成功后的邮件通知也会增加说明 GitHub Actions 的信息。

Hi sy-records!  A new version of the package @sy-records/docsify-footnotes (2.3.0) was published at 2026-04-21T02:48:22.069Z from GitHub Actions: https://github.com/sy-records/docsify-footnotes/actions/runs/24701393194/attempts/1 (triggered via a "push" event on git ref "refs/tags/v2.3.0"). The shasum of this package is 8136f65cb7d651d4b3671290b7c16da4cac71b24.  If you have questions or security concerns, you can contact us at https://www.npmjs.com/support.  Thanks,  The npm team. 

需要注意的是 Trusted Publishing 需要 npm CLI 版本 11.5.1 或更高版本以及 Node 版本 22.14.0 或更高版本。

Trusted Publishing 是 npm 在供应链安全方向的重要升级，建议所有开源项目逐步迁移。