npm stage-only 令牌和可信发布分别管什么
stage-only 控制自动化能否直接发布,可信发布处理工作流的身份认证。配置发布流水线时,这两个问题都要检查。
先确认谁能准备版本、谁批准发布,再选择身份方案。stage-only 仍有包写权限,需要按写令牌保护。
相关信息
- stage-only
- 允许准备待审查版本,发布需要后续批准
- OIDC 可信发布
- 以受信工作流换取发布身份,减少长期令牌依赖
- 容易忽略
- stage-only 仍保留其他包写权限
- 适用检查
- CLI/运行环境、runner 与身份配置以 npm 当前文档为准
stage-only 留下了人工批准这一步
stage-only 令牌允许自动化准备待审版本,但不能直接发布新版本。维护者审核并批准后,版本才会发布。
它仍保留一些包写权限。npm 公告举出的例子包括移动 dist-tag 和废弃版本,因此不能把这种令牌当成只读凭证。
可信发布解决长期令牌的问题
可信发布通过受信工作流与 npm 建立身份关系,减少在 CI 中长期保存发布令牌的需要。它与 stage-only 处理的是不同环节:一个关乎身份从哪里来,一个关乎准备版本后是否还需要批准。
具体能用哪种方式,要核对 npm 当前支持的 runner、CLI 和运行环境,以及工作流身份配置。
把发布过程逐段查一遍
可以先画出代码、构建产物、npm 注册表之间的流程,再逐段检查权限。仅看仓库里的代码还不够,实际准备或发布的产物也需要能对应到这次构建。
| 环节 | 要回答的问题 |
|---|---|
| 代码进入工作流 | 谁能修改发布配置,什么条件可以触发? |
| 工作流生成产物 | 待审版本来自哪次构建,是否就是准备发布的那一份? |
| 产物进入注册表 | 谁批准,最终用什么身份发布? |
迁移从一条低影响流程开始
先列出现有令牌绑定的包和允许动作,确认目标配置支持后,再选择一条低影响流程迁移。检查批准步骤、实际发布身份和恢复方法,完成后清理不再使用的长期令牌。
stage-only 的剩余写权限也要一并记录,不能只留下“禁止直接发布”这一项。
资料来源
依据文末资料整理,未做环境实测。编辑与更正说明。
修订记录
2026-10-26:首次发布。
2026-10-27:编辑修订:重写标题、导语和正文,删去重复提示,保留技术范围、来源与原发布时间。