用途:为 npm 生态项目(单包或 monorepo,有无版本管理工具均可)接入统一发版标准,或按标准执行发版。核心原则是发出去的版本收不回,能在发布前做的检查全部前置,发布、打 tag、建 Release 放在最后;发布可安全重跑,registry 上已有版本自动跳过;成功与否以 npm view 查询为准,不以命令输出为准;发版脚本不交互,所有输入来自参数。
两套标准:公开发版发布到 npmjs 与 GitHub Release,由 CI(GitHub Actions + npm trusted publishing,OIDC 无凭证)执行,本地脚本负责检查、升版本、构建测试、提交、推送;本地发版发布到私有 registry,由本机 release 脚本完成检查、升版本、构建、打包校验、提交推送、发布、打 tag,凭证由用户写入用户级 ~/.npmrc。
共同契约:入口为根 package.json 的 release 脚本,支持 --dry-run 演练并恢复工作区;起点要求工作区干净、在发版分支、不落后远端;有版本工具时由工具计算版本,无工具时传 release <x.y.z>;先提交推送发版提交再发布,tag 只在发布成功后创建;提交信息为 chore(release): 发布 …,tag 命名与 dist-tag 规则见参考文件,预发布版绝不落到 latest;传参统一写成 <pm> run release -- <参数>。
项目配置:发版标准记在仓库根 .pe.jsonc 的 release_mode(public 或 local),凭证不进仓库。流程为识别项目(标准、包管理器、可发布包、版本工具、设施)、接入或修正(读对应参考文件,列出改动并确认,接入改动单独提交)、执行发版(定内容、给计划、演练、执行、验证、报告)。验证公开发版需跟踪 CI 到结束并查 npm view 与 GitHub Release;本地发版以脚本 registry 查询为准。注意 pnpm ≥ 11 与新版 Yarn 默认不安装发布不满一天的版本,下游需配置相应排除项。
限制:其他版本工具(release-please、semantic-release、Nx Release 等)暂无参考文件,需先查官方最新文档;OTP 或登录需用户自行完成,Agent 不代填;禁止回滚或改写已发布版本、移动 tag、force push 发版分支。