发布
LoggerJS 使用 Changesets 管理版本，并通过 GitHub Actions 的 release workflow 发布到 npm。
本地验证
准备发布前，先运行完整的发布演练：
pnpm release:dry-run它会运行常规质量门禁，验证公开导出和 API 报告，用 npm pack --dry-run --json 检查每个包，把按发布方式打出的 tarball 安装到临时的消费方项目中做冒烟测试，打印 Changesets 状态，并运行 pnpm publish -r --dry-run --access public --no-git-checks --json。
不实际发布的 canary 验证：
pnpm release:canary:dry-run真正的 canary dist-tag 只应在带版本号的预发布分支或 workflow 中使用：
pnpm check
changeset publish --tag canary新组件发布检查
如果一次发布新增了公开的 transport 或 integration 子路径，确认变更中包含：
docs/TRANSPORTS.md或docs/INTEGRATIONS.md中的稳定性分级；- 由
pnpm verify:component-docs检查的导入边界文档； - 与组件相符的运行时验证：浏览器生命周期/存储行为用浏览器 E2E，edge/运行时相关的说法用运行时冒烟测试，本地服务用基于 Docker 的真实服务测试，托管厂商用外部服务冒烟测试；
pnpm size:check的体积预算数据，任何预算上调都要在变更中说明理由；- 生产文档中写清投递、重试、隐私和凭据存放方面的注意事项。
每次发版
- 在发版提交上手动运行
Soakworkflow，设置更长时长（major 版本用 60 分钟），确认两个浸泡测试都通过。每个浸泡测试在单独的 job 中运行，超时上限为 90 分钟。 - 审查
packages/*/test/golden/下的任何 diff：它会改变收集端收到的内容，需要写进发版说明。 - 发布之后，把
examples/browser-basic/package.json中的@loggerjs/browser-previous指向刚发布的版本，让升级测试始终打开上一个已发布版本写入的数据，并把pnpm-workspace.yaml中minimumReleaseAgeExclude的精确版本替换为该别名现在安装的版本。从 1.0 开始只有 browser 包：core 是它的 peer dependency，所以该别名使用工作区里的 core。 - release workflow 成功后，为该 tag 创建 GitHub Release，并且不要创建新的 tag，例如
gh release create v1.2.0 --verify-tag --title 1.2.0 --latest --notes "**Full Changelog**: https://github.com/jskits/loggerjs/compare/v1.1.0...v1.2.0"。每个已发布的版本都有对应的 GitHub Release。npm 可能需要几分钟才能在各处显示新版本，所以在宣布发布之前，请反复检查 registry，直到每个包都显示该版本。
npm 发布
发布 workflow 是 .github/workflows/release.yml。每个可发布的 @loggerjs/* 包都应在 npmjs.com 上配置 Trusted Publisher：
- Organization or user:
jskits - Repository:
loggerjs - Workflow filename:
release.yml - Allowed action:
npm publish
workflow 通过 npm Trusted Publisher/OIDC 发布，不读取 NPM_AUTH_TOKEN、NPM_TOKEN 或 NODE_AUTH_TOKEN。
permissions.id-token: write允许 GitHub Actions 签发 OIDC token，npm 会在npm publish期间用它换取发布权限。actions/setup-node只为发布命令设置 npm registry，不配置长期有效的 token。- 发布任务运行在 GitHub 托管的 Ubuntu runner 上，使用 Node 24 并升级到 npm 11，以获得最新的 Trusted Publisher 支持。
- 发布前，发布任务会运行
pnpm release:publish:preflight，为每个尚未发布的包交换一次 GitHub OIDC token。这样可以在发布任何新版本之前发现缺失或不匹配的 Trusted Publisher 配置。 - 每个可发布的包都设置了
publishConfig.provenance=true，发布步骤设置NPM_CONFIG_PROVENANCE=true，发布脚本也会显式给pnpm publish传入--provenance。 npm whoami不适合作为 Trusted Publisher 的预检，因为 OIDC 认证只在发布操作期间存在。
npm 要求 provenance 来自公开的源码仓库，并且包的 repository 元数据必须与该仓库一致。
普通提交不会触发发布。发布流程是：先用 pnpm version-packages 消费待处理的 changesets（它同时会重新生成列出包版本的站点参考页），提交更新后的包版本信息和重新生成的文档，并让这次提交通过常规 CI。版本提交合入 main 后，创建并推送与新版本号一致的 release tag，例如 v0.5.6；.github/workflows/release.yml 只监听 v* tag 的推送，并拒绝不在 origin/main 可达范围内的 tag。如果仍有待处理的 changesets，发布任务会直接失败；否则它会为每个尚未发布的包验证 npm OIDC 权限，运行 pnpm release:publish，用 pnpm publish --provenance 发布每个尚未发布的 workspace 包，然后用幂等的 changeset tag 命令创建各包的 release tag，最后推送 @loggerjs/* 包 tag。
如果 npm 在发布或 pnpm release:publish:preflight 期间返回认证错误，请检查每个包的 Trusted Publisher 配置是否与仓库所有者、仓库名、workflow 文件名、可选的 environment 名称以及 allowed action 完全一致。npm 只在交换 OIDC 权限或尝试发布时才会检查这些字段。发布脚本可以安全重跑：已发布的包版本会被跳过，只发布剩余的包。
参考：