跳到正文

发布知识库

发布链

  1. 两个仓库完成 lint、类型、覆盖率、build、Silen audit/eval、pack 和浏览器 E2E。
  2. 核验 npm 身份与 vue-audio-native 原包维护权限；权限缺失时停止，不改包名。
  3. 首次引导发布 core beta.1、Vue beta.1，并以 Vue beta.2 修复严格 TypeScript 声明回归。
  4. 后续 OIDC 发布按 core beta.2 → Vue beta.3 → React beta.2 的顺序推进。
  5. 在完全干净的 Vite、Nuxt、React 和 Next 消费者中验证 registry 包与精确 core 依赖。
  6. 三个包与干净消费者回归全部通过后，将 vue-audio-native@0.1.41 设置为 legacy。
  7. 稳定 1.0 由完整真机证据或维护者版本绑定评估授权二选一放行，随后只通过 OIDC 发布。
  8. 1.0.1 通过同一评估路径发布 core 与 Vue 的文档和发布安全补丁，并用全新 Vite Vue 与 Nuxt SSR 消费者复核 npm Registry；这次补丁没有改变音频运行时。

首次 beta 引导发布（已完成）

新包尚不存在时，无法先在 npm 包设置页绑定 Trusted Publisher。首次 beta 曾使用受保护的 手动工作流与设有 90 天到期上限的 Granular Access Token 引导。OIDC 迁移完成后，所有者 决定保留这枚已与仓库断开的 token 至 2026-10-28；它不能重新进入 Secret、工作流或本机 npm 配置。完成顺序如下：

  1. 在 npm 网站创建仅用于引导的 Granular Access Token：有效期上限为 2026-10-28， Packages and scopes 设为 Read and write、选择 All Packages、开启 bypass 2FA，Organizations 设为 No access。
  2. 将 token 保存到 Vue 和 React 两个仓库的 GitHub npm Environment Secret NPM_BOOTSTRAP_TOKEN；不写入本机 .npmrc、代码、日志或 PR。
  3. Vue 仓库先运行完整门禁并按 core → Vue 顺序发布，声明修复以 Vue beta.2 更新到 next。
  4. React 仓库改用 registry core、通过门禁并发布 React beta 后，完成四类干净消费者回归。
  5. 三个 beta 都可查询且四类消费者通过后，将 Vue 2 的 0.1.41 设置为 legacy。
  6. 删除两个 GitHub Secret；根据所有者决定，npm 账户中的 token 保留至到期，但不再用于 项目发布。
  7. 为已创建的三个包绑定 .github/workflows/release.yml、GitHub npm Environment 与 npm publish Trusted Publisher；后续发布只使用 OIDC。Vue 仓库绑定 @trsoliu/audio-core 与 vue-audio-native，React 仓库绑定 react-audio-native。

三个 Trusted Publisher 已于 2026-07-30 配置并逐项核验；引导工作流和仓库 Secret 已移除， 两个 GitHub npm Environment 的 Secret 数量均为 0。保留的账户 token 不属于项目发布 链路；后续只能由 Trusted Publisher 获取短期 OIDC 凭据。三个发布包都通过 publishConfig.registry 固定到官方 npm registry，不受本机安装镜像配置影响；首次 beta 保留 provenance，后续版本必须由 .github/workflows/release.yml 和 Trusted Publishing 的 短期 OIDC 凭据发布。

后续 beta（OIDC）

后续 beta 在 Changesets beta pre mode 中生成版本，release PR 可以在稳定证据尚未放行 时合并。Changesets 在 pre mode 会保留源 changeset 文件，因此工作流只有在每个面向发布包 的非空文件都已出现在 pre.json 的 consumed 列表中时，才认定 beta 版本 PR 已合并；仅面向 私有 Demo/fixture 的 changeset 不阻塞 npm 发布，其他尚未消费的变更只会创建或更新版本 PR。 工作流还要求当前 push 同时新增 consumed 记录并改变至少一个发布 manifest 的版本，确保只有 version PR 的合并提交能够发布；失败时应重跑原 Actions run，后续普通提交不会补发旧版本。 push 事件的 previous SHA 必须仍是 HEAD 的祖先，并且完整 diff 只能包含 pre state、发布 manifests、生成的 package changelog 与 lockfile。这既兼容多提交 rebase merge，也会拒绝批量 push 夹带未版本化源码。进入可发布状态后，工作流再确认 core 与 Vue manifests 都是 *-beta.N 且 Vue 精确依赖本次 core，最后由 TypeScript 发布器按 core → Vue 顺序对 registry 中尚不存在的版本执行 npm publish --tag next --provenance。对已存在版本，发布器会通过 有界的 fresh/no-cache 重试确认 next 精确解析到该版本；查询期间的瞬时网络或 registry 错误也会在同一窗口内重试，否则失败而不是把过期 dist-tag 当作成功。部分成功后重跑原 run 仍然幂等。这条路径只使用 Trusted Publishing 的短期 OIDC 凭据与 provenance，不读取 npm token。

如果原发布 run 已无法重跑，可在 master 手动 dispatch，并填写失败 push 记录中的 previous default-branch SHA 与 exact release HEAD SHA。工作流会先要求当前 HEAD 与填写的 release SHA 完全一致，并实时确认 origin/master 仍指向同一提交，再复用相同的 consumed/version transition、祖先关系和完整 diff 白名单。push 与手动路径都会在 npm publish 前再次读取远端 分支；版本提交后出现任何后续提交或运行中发生竞态 push 都会拒绝发布，因此恢复路径不会扩大 发布边界。

发布 job 只允许在 master 上运行；从 release PR 分支手动 dispatch 不会获得发布路径。 适配器发布前还会确认其精确 @trsoliu/audio-core 版本已经由本次顺序发布或 npm registry 提供，防止产生不可安装的依赖图。

不处于 active pre mode（包括 pre exit 过渡）时，工作流只会走稳定发布分支，并强制执行 稳定证据门禁。因此 beta 发布不能把 latest 切到未评估的稳定版本，稳定发布也不能借用 next 路径绕过版本绑定授权。

稳定发布还必须来自 Changesets 生成的版本提交：previous SHA 必须是当前提交的祖先，至少一个 面向发布包的 changeset 必须在该提交中删除，包版本必须单调前进，完整 diff 只能包含 Changesets 状态、manifests、package changelogs、受管理的 package README 安装区和 lockfile。 工作流在发布前再次确认远端 master 仍指向同一版本提交；普通源码或文档提交不会直接发布。

本次切换先把随公开 beta 发布过的 modern-audio-native 与 safe-vue-declarations 记为 consumed；随后 clear-audio-api-docs 也由 beta 版本 PR 消费，并生成已发布的 core beta.2 与 Vue beta.3。

证据不是声明

本地 workspace link、成功的 npm pack 或桌面浏览器 E2E 都不能证明 registry 安装和宿主 WebView 行为。发布记录必须保留包版本、dist-tag、registry 查询、消费者构建、commit SHA、 对应 CI URL，以及真机证据或维护者评估与风险接受记录。

稳定发布

稳定版通过 GitHub Actions Trusted Publishing、OIDC 与 provenance 发布。工作流不保存长期 npm token。pnpm release:verify-stable 会在 publish 之前解析 兼容性评估与真机记录：四个必需环境都精确为 通过 时采用真机证据； 否则必须提供维护者、ISO 日期、精确稳定版本覆盖、自动化评估 通过 和剩余风险 已接受。 工作流会要求所有传入 manifest 要么匹配单一共享版本，要么被完整的 包名@版本 映射精确覆盖。 1.0.0 与 1.0.1 采用维护者评估路径，未执行的真机项保持明确标记，不会被写成通过。

1.0.1 的稳定发布流水线、npm provenance 与 Registry 消费者验证已于 2026-07-30 完成； @trsoliu/audio-core@latest 和 vue-audio-native@latest 均解析到 1.0.1，Vue 精确依赖同版本 core，legacy 仍解析到 0.1.41。对应 GitHub Release 为 Vue Audio Native 1.0.1。

Vue 仓库采用 core 与组件协调版本。pnpm version-packages 在 Changesets 更新 manifests 后， 同步重写两个 package README 的受管理安装区，再以 --lockfile-only --ignore-scripts 刷新 pnpm lockfile，保证 npm 页面、精确版本和 release PR 一致，并确保版本阶段不执行依赖生命周期脚本。