Native SDK 版本发布全流程指南：从版本号同步到 npm 可信发布

桌面应用跨平台【免费下载链接】nativeToolkit for building native desktop apps项目地址https://gitcode.com/gh_mirrors/ze/native点击查看免费下载Native SDKnative-sdk/cli的发布是一套人工驱动的单 PR 流程由维护者在本地完成版本号提升、changelog 编写与 PR 合并随后 CI.github/workflows/release.yml自动完成跨平台交叉编译、GitHub Release 资产上传与九个 npm 包的分批发布。本文基于仓库根目录的 RELEASING.md 编写并结合 packages/native-sdk 下的版本同步脚本与 release.yml 工作流源码完整讲解准备一次发布 → 写好 changelog → CI 自动发布的每一步以及其中关键的版本一致性校验与 npm OIDC 可信发布配置。发布策略为什么是人工 单 PR仓库的发布模型非常明确Releases are manual, single-PR affairs——发布不依赖自动打 tag 的机器人而是由维护者在分支上完成全部准备工作后通过一个 PR 合并到main触发。这样设计的目的从 RELEASING.md 原文及源码推断在于维护者掌控 changelog 的措辞与格式发布说明的语气、分类和细节粒度由人决定而非自动生成的 commit 列表一次变更只走一个 PR版本号提升、changelog 条目、以及同步脚本对多处文件的改动全部收拢在同一个 PR 中便于 review 与回滚CI 负责机械性工作合并后流水线自动完成编译、发布和校验人工不触碰任何 npm 凭据。整个流程分为两段本地准备第 1 步到第 7 步与 CI 自动发布合并后触发。发布准备七步操作清单按 RELEASING.md 的步骤一次发布的本地准备如下创建分支例如prepare-v1.2.0提升版本号修改packages/native-sdk/package.json中的version字段当前仓库中为0.10.1见 package.json同步所有版本引用运行npm --prefix packages/native-sdk run version:sync审阅自上次发布以来的 git 历史在 CHANGELOG.md 顶部、新的## version标题下撰写完整的 changelog 条目并用!-- release:start --与!-- release:end --标记包裹填充条目的### Contributors从发布区间内的 commit 作者与Co-authored-by尾注中提取优先使用 GitHub handle这段被标记包裹的内容同时就是 GitHub Release 的正文移除上一条发布的!-- release:start --/!-- release:end --标记——只有最新一条发布允许保留标记打开 PR 并合并到main。第 3 步version:sync是保证一个版本号统治所有文件的关键下面单独展开。版本同步一个版本号八处落地version:sync由 scripts/sync-version.js 实现其注释开宗明义One version number rules them all。packages/native-sdk/package.json是唯一事实来源脚本把该版本号逐一写入以下位置落点文件路径说明CLI 源码tools/native-sdk/main.zig当前为const version 0.10.1;见 main.zig#L9native version命令输出的版本号8 个平台二进制包packages/native-sdk/npm/platform/package.json每个包的version字段同时把主包的repository.url与homepage一并复制过去主包 optionalDependencies 引脚packages/native-sdk/package.json8 个native-sdk/cli-*平台包的精确版本引脚如native-sdk/cli-linux-x64-gnu: 0.10.1打包的 TS 核心packages/core/package.json 与 packages/core/package-lock.jsonnative-sdk/core与 CLI 共享同一发布版本manifest 与 lockfile 的自引用版本字段都会被盖章已提交的 TS 示例examples/*/package.json自动发现并更新所有依赖native-sdk/core的示例的精确引脚引脚之所以全部使用精确版本而非区间是为了保证某个版本的native-sdk/cli安装到的二进制一定构建自同一个 commit 的源码——optionalDependencies的 8 个引脚精确到0.10.1主包落地时平台包必须已存在且版本一致。同时脚本还会传播仓库身份字段repository.url、homepage注释明确指出npm 会用repository.url校验发布 provenance若仓库改名只更新了主包而遗漏平台包发布会在 provenance 校验处失败。对应的校验脚本是 scripts/check-version-sync.js它逐项核对上述所有位置是否与主包版本一致并在 CI 发布前运行见下文。此外它还校验两处特殊引脚typescript/old即npm:typescriptX.Y.Z的别名引脚CLI 与packages/core必须使用完全一致的精确别名形式防止新安装的 CLI 解析到与开发环境不同的 TypeScript 编译器scriptc外部核心编译器同样是精确版本且两份 manifest 必须一致。任何一处漂移都会导致version:check报错并以非零退出码终止发布。编写 changelog格式、语气与标记约定CHANGELOG.md 是发布说明的唯一来源其书写规范如下分组标题按### New Features、### Bug Fixes、### Improvements等描述性标题归类条目格式每条 bullet 先给加粗的引导语如**JSON manifests by default**随后跟一句简洁描述末尾在可用时标注 PR 编号如(#385)禁止前缀不要用 commit hash 作为条目前缀覆盖完整区间条目必须覆盖自上次发布以来的完整 git 区间包括那些单独 PR 并未改动CHANGELOG.md的变更Contributors 来源从发布区间内 commit 作者与Co-authored-by尾注提取优先使用 GitHub handle。关于标记约定仓库现状可以验证规则最新发布条目当前为## 0.10.1由!-- release:start --与!-- release:end --包裹见 CHANGELOG.md#L5-L17更早的发布如## 0.10.0、## 0.9.5则没有标记——这正是只有最新发布保留标记规则的落地结果。CI 提取正文的方式见 release.yml用awk在两个标记之间截取内容写入临时文件并校验行数不少于 2否则报错退出。因此标记缺失或位置错误会直接阻断 GitHub Release 创建。CI 自动发布流水线合并到main后.github/workflows/release.yml 触发包含三个按依赖顺序执行的 job1. check-release决定要不要发在 ubuntu-latest 上运行把本地packages/native-sdk/package.json的版本与 npm 上的native-sdk/cli版本对比release.yml#L32-L80版本不同npm 上还没有这个版本→should_releasetrue同时需要创建 GitHub Release版本相同→ 检查v版本这个 tag 的 GitHub Release 是否已包含全部 8 个二进制资产与CHECKSUMS.txt资产齐全 → 跳过发布needs_github_releasefalse缺少任一资产 → 仅重建/补齐 GitHub Releaseneeds_github_releasetrue不重新发布 npm。这个分支设计保证了npm 已有该版本但 Release 资产缺失时CI 可以从标记的 changelog 条目重建 GitHub Release实现幂等修复。2. github-release交叉编译并上传资产在 macos-14 上运行条件为needs_github_release true先用 awk 提取 changelog 正文再执行 scripts/build-binaries.sh 用 Zig 交叉编译全部 8 个平台目标最后gh release create/gh release upload上传二进制与校验和。build-binaries.sh中的目标表build-binaries.sh#L20-L29给出了 npm 平台键、Zig 目标与 Release 资产名的完整对应关系npm 平台包Zig 目标GitHub Release 资产darwin-arm64aarch64-macosnative-sdk-darwin-arm64darwin-x64x86_64-macosnative-sdk-darwin-x64linux-arm64-gnuaarch64-linux-gnunative-sdk-linux-arm64linux-x64-gnux86_64-linux-gnunative-sdk-linux-x64linux-arm64-muslaarch64-linux-muslnative-sdk-linux-musl-arm64linux-x64-muslx86_64-linux-muslnative-sdk-linux-musl-x64win32-arm64aarch64-windowsnative-sdk-win32-arm64.exewin32-x64x86_64-windowsnative-sdk-win32-x64.exeZig 可以从任意宿主交叉编译全部 8 个目标脚本只构建 CLI 可执行文件zig build cli以保持循环快速。你也可以传平台键子集如build-binaries.sh darwin-arm64只构建部分目标。3. publish分批发布九个 npm 包在 ubuntu-latest 上、environment: Release中运行条件为should_release true且 GitHub Release job 成功或被跳过release.yml#L138-L255。步骤依次为版本一致性门禁npm run version:check即上文check-version-sync.js与scripts:check半吊子提升的提交树会被当场拒绝下载并校验二进制从 GitHub Release 下载 8 个资产sha256sum -c CHECKSUMS.txt验证完整性staging 到平台包按资产名 → 平台键的映射表与build-binaries.sh相同把二进制放入packages/native-sdk/npm/key/bin/native[.exe]并置为可执行分批发布顺序敏感先发布 8 个平台包packages/native-sdk/npm/*/每包npm publish --provenance --access public最后发布主包native-sdk/cli。已存在同版本号的包自动跳过npm view nameversion检查保证重跑幂等。这样做的原因主包的optionalDependencies精确引脚只有在所有平台包都已上线后才能解析成功native-sdk/core的发布开关packages/core/package.json中private: true字段本身就是发布开关——为 true 时跳过发布去掉该字段后同一段逻辑会开始发布该包无需改动工作流。注意在去掉标记之前必须先为native-sdk/core在 npmjs.com 配置好可信发布者否则首个公开版本会在该步失败。npm 可信发布OIDC无 token 的发布安全发布采用npm trusted publishingOIDC仓库中不存在任何 npm token 密钥。其原理是publish job 声明了id-token: write权限release.yml#L148-L150GitHub Actions 据此向 npm 换取短时凭证每次发布都带--provenance。一次性配置要求在 npmjs.com 上完成九个包native-sdk/cli加上packages/native-sdk/npm/下的 8 个native-sdk/cli-*平台包各自配置一个 GitHub Actions trusted publisher指向Repositoryvercel-labs/nativeWorkflowrelease.ymlEnvironmentRelease若某个包缺少该配置npm publish会针对该包大声失败抛出 OIDC 认证错误——不会静默跳过。可信发布还要求 npm ≥ 11.5.1由工作流使用的 Node 24 自带的 npm 满足。这套机制的收益是双重的既消除了 token 泄露面又因为每次发布都带--provenance消费者可以审计每个发布版本的构建来源。发布后的验证闭环一次成功的发布最终可验证的产物包括GitHub Releasev0.10.1标题、正文来自标记的 changelog 条目8 个二进制 CHECKSUMS.txtnpm 上native-sdk/cli-linux-x64-gnu等 8 个平台包os/cpu/libc字段由 npm/linux-x64-gnu/package.json 等清单声明如linux/x64/glibc最后上线的native-sdk/cli其optionalDependencies精确指向同版本的平台包仓库内tools/native-sdk/main.zig的const version、packages/core的 manifest 与 lockfile、各示例的引脚全部与主包版本一致由version:check强制。对维护者而言下次发布只需重复七步清单分支 → 提升版本 → version:sync → 写 changelog带标记→ 填 Contributors → 清理旧标记 → 合并 PR剩余的全交给流水线。参考路径速查发布流程文档RELEASING.md版本同步脚本packages/native-sdk/scripts/sync-version.js版本一致性校验packages/native-sdk/scripts/check-version-sync.js发布工作流.github/workflows/release.yml交叉编译脚本packages/native-sdk/scripts/build-binaries.sh主包清单packages/native-sdk/package.json平台包示例packages/native-sdk/npm/linux-x64-gnu/package.json变更日志CHANGELOG.mdCLI 版本号常量tools/native-sdk/main.zig#L9赞分享桌面应用跨平台【免费下载链接】nativeToolkit for building native desktop apps项目地址https://gitcode.com/gh_mirrors/ze/native点击查看免费下载相关推荐JSONEditor 版本发布全流程指南从版本号更新到 npm 发布JSONEditor 版本发布全流程指南从版本号更新到 npm 发布 导读 jsoneditor 是一个基于 Web 的 JSON 查看、编辑、格式化与校验工前端UI组件MediaElement.js 版本发布全流程从发布分支、版本号同步到 Grunt 构建与 npm 发布的实操指南MediaElement.js 版本发布全流程从发布分支、版本号同步到 Grunt 构建与 npm 发布的实操指南 本文以仓库根目录的 RELEASE.md音视频前端UI组件webamp 项目 npm 发布流程完全指南从版本号同步到 CI 自动化发布与 npm provenancewebamp 项目 npm 发布流程完全指南从版本号同步到 CI 自动化发布与 npm provenance 导读 本文以 .claude/skills/re前端音视频上一篇揭秘github-automated-repos工作原理GitHub API交互与数据处理流程下一篇性能调优检查清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考