node-release

node-release

自动完成版本管理和 npm 发布，无需长期有效的密钥，也不依赖猜测。此工具要解决的问题：模型在 2026 年仍配置 NPM_TOKEN 密钥；没注意到软件包的首个版本无法通过 OIDC 发布；受信任发布者的注册细节出错（大小写、文件名、间接调用）；发布在打标签后失败时，发布流程只完成了一半。

不适用场景

• 导出映射、打包、tarball 内容 → node-packaging（发布流程假设其检查已通过）。
• 验证依赖项的来源证明 → node-supply-chain。
• 测试／lint CI → node-ci。

工作流

1. 根据工作流的实际需求选择发布工具（决策表见 references/release-playbook.md）：Changesets（人工编写说明，适用于 monorepo）、semantic-release（严格遵循约定式提交，完全自动化）、release-please（每次发布都通过 PR 审核）。
2. 受信任发布（OIDC）——默认身份验证方式；操作手册按版本列出所有要求，并附有 npm 官方文档链接（运行器上的 CLI／Node 最低版本、GitHub 托管运行器、仓库和工作流文件名必须完全匹配、workflow_call 间接调用注意事项）。使用受信任发布时，会自动附加来源证明。
3. 引导发布的注意事项——要在问题出现前说明：全新的软件包无法通过 OIDC 首次发布；操作手册中的引导流程涵盖一次手动发布，随后进行注册、撤销令牌，并在账户级别强制仅允许受信任发布。
4. 根据操作手册中的 YAML 编写发布工作流：采用最小权限（仅在需要时设置 id-token: write、contents: read/write），第三方操作固定到 SHA（符合 node-supply-chain 策略），发布前必须通过 node-packaging 检查。
5. 严格控制失败顺序：先发布再打标签（或确保重试具有幂等性）；绝不删除已发布的标签——发布不可变。
6. 端到端验证：先试运行，再尽可能实际发布一个预发布版本／dist-tag；在注册表页面确认来源证明；确认无误后再撤销旧令牌。

输出规范

一条可用的自动发布流水线：版本号 + 更新日志 + 标签 + 带来源证明的 npm 发布；切换完成后不再保留长期有效的注册表密钥；在代码库中记录引导发布和回滚流程；有意决定是否使用分阶段／预发布渠道。

注意事项

• 受信任发布者注册必须完全匹配：所有者／仓库的大小写，以及包含扩展名的工作流文件名；如果从可复用的（workflow_call）工作流发布，则会根据调用方文件进行验证。
• OIDC 不会让遭到入侵的工作流变得安全——它消除的是存储密钥被盗的风险；仍须审查工作流文件（在 .github/ 上配置 CODEOWNERS）。
• 先打标签再失败，会导致使用者看到 npm 上并不存在的版本——必须明确选择顺序控制或幂等性。
• 所有 npm 端的具体要求（最低版本、分阶段发布、令牌有效期）都会变化：操作手册按版本列出各项要求及其主要来源——配置时请重新核实。

文件

• references/release-playbook.md — 工具决策表、附有按版本划分的要求及文档链接的 OIDC 设置、引导流程、发布工作流 YAML、失败顺序模式、dist-tag／预发布版本指南。