使用 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 出现之前，常见流程如下：

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

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

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

Trusted Publishing 的工作原理

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

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

Trusted Publishing 基于以下流程：

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

整个过程：

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

设置 Trusted Publishing

我也是在发布 docsify-footnotes时发现 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: Publish Package

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: npm ci
      - run: npm run build --if-present
      - run: npm test
      - run: npm publish

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

发布成功后的邮件通知也会增加说明 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 在供应链安全方向的重要升级，建议所有开源项目逐步迁移。