npm 包自动发布(Trusted Publisher + GitHub Actions)

为 npm 包项目落地"push v* 标签 → 自动发布到 npmjs"的发布工作流。认证走 npmjs.com 的 Trusted Publisher(OIDC):workflow 内零 token、零 secret,并自动生成 provenance。本 skill 备两套发布流:直接流(tag push 即发布,无人工闸门,默认)与 暂存流(CI 暂存,维护者本地 npm stage approve 2FA 放行,按仓库约定选用)。

执行须知(重要,先读)

npm 发布链路里有几步一旦执行就不可逆(git push --tags、npm publish、npm stage approve),而排查一次 401/403 往往要来回改 workflow、重新绑定 Trusted Publisher、重新 tag,比多花十秒核对便宜得多。所以本 skill 的每一步都按"先核对、再执行"的顺序写,执行前务必做到:

• 每个"完成判据"都要用命令的实际输出核对,不要凭上一步的记忆判断"应该没问题"。 例如步骤 1 摸底完的每一项,都应该是刚跑完对应命令、亲眼看到输出后填的值,而不是根据文件名或项目类型推测的。
• 命令与旗标只从本 skill 正文、references/workflow-template.yml、references/workflow-template-staged.yml、references/troubleshooting.md 里取,不要凭印象改写或补充(尤其是 npm stage 子命令和 gh 参数)。 这两个工具改动较快,凭记忆拼出的旗标很容易是过时或不存在的;不确定时先 npm stage --help / npm publish --help / gh release create --help 核实存在,再使用。
• git push / npm publish / npm stage approve、以及 gh release create/edit(写发布说明,对外发布)这类不可逆或对外操作前,先把"我即将执行 X,因为 Y"说给用户听一遍,拿到当轮的明确授权再动手,不要因为前面步骤顺利就自动往下推进到发布。
• 遇到报错时,先去 references/troubleshooting.md 按症状查,不要凭经验改一个旗标就重试——同一条错误往往有好几种表面相似但处理方式不同的原因(比如 401 既可能是 token 权限边界,也可能是 workflow 文件名不匹配)。

步骤