• 桌面应用
• 跨平台
• 移动开发

本篇技术指南以 Tauri 仓库根目录下的 .changes/README.md 为核心，系统讲解 Tauri 基于 covector 的"变更文件（change file）"驱动版本管理机制：包括变更文件的创建流程、frontmatter 格式、major/minor/patch 语义化版本规则、变更标签分组，以及 .changes/config.json 中完整的包管理与发布流水线配置。读完本文，你将掌握在 Tauri 这类多包（Rust crate + npm 包）仓库中如何通过.changes目录提交一次合规的版本变更，并理解依赖包如何被自动联动升版。

一、为什么需要变更文件：covector 与.changes目录

Tauri 是一个典型的 monorepo 仓库，同时维护着多个独立发布的包——既有crates/下的 Rust crate（如tauri、tauri-bundler、tauri-cli、tauri-utils等），也有packages/下的 npm 包（如@tauri-apps/api、@tauri-apps/cli）。每个包遵循各自的语义化版本节奏，若全部依赖人工手写 CHANGELOG 与版本号，在多包并行演进时极易出现遗漏或冲突。

为此，Tauri 采用 jbolda/covector 驱动的"变更文件（change file）"机制。其核心思路是：在创建 PR、做出需要升版（version bump）的改动时，开发者不必直接修改任何版本号，而是在.changes/目录下新增一个 Markdown 文件，只声明"本次改动属于什么类型的 bump"以及"改了哪个包"。版本号的实际提升、CHANGELOG 的生成、依赖包的联动升级，全部交给 covector 在发布流程中自动完成。

从仓库现状看，.changes/ 目录目前包含三个文件：

• README.md：变更文件编写规范（本文核心）
• config.json：covector 的完整配置（包清单、标签、发布命令）
• bundler-freebsd-glob-error.md：一个真实的变更文件示例

二、变更文件的基本规则

2.1 何时创建、如何命名

As you create PRs and make changes that require a version bump, please add a new markdown file in this folder.

当你创建 PR、且改动需要触发版本提升时，就在.changes/目录下新增一个 Markdown 文件。需要注意：

• 文件扩展名必须为.md，否则不会被识别；
• 文件名不重要，covector 不依赖文件名做任何语义判断；
• 但官方建议文件名能体现整体变更内容，便于组织与检索。例如仓库中实际存在的bundler-freebsd-glob-error.md，一看便知是"tauri-bundler 在 FreeBSD 平台 glob 报错"的修复。

2.2 声明 bump 类型，而非具体版本号

变更文件不写具体的版本号数字，只写期望的 bump 类型：major、minor或patch。这样避免开发者在 PR 阶段就猜测最终版本号，把版本决策延迟到发布阶段统一计算。

2.3 不需要手动考虑依赖

When you select the version bump required, you donotneed to consider dependencies. Only note the package with the actual change, and any packages that depend on that package will be bumped automatically in the process.

选择 bump 类型时无需考虑依赖关系：只标注"实际发生改动"的那个包；凡是依赖它的包，会在发布流程中被自动提升版本。这一点在 .changes/config.json 的packages配置中有直接体现，例如：

• tauri-bundler声明"dependencies": ["tauri-utils", "tauri-macos-sign"]
• tauri声明"dependencies": ["tauri-macros", "tauri-utils", "tauri-runtime", "tauri-runtime-wry", "tauri-build"]
• @tauri-apps/cli声明"dependencies": ["tauri-cli"]

一旦tauri本体 bump，其五个 Rust 依赖 crate 会自动跟随调整版本，开发者只需专注自己真正改动的那一个包。

三、变更文件的标准格式

变更文件采用"YAML frontmatter + 自由文本摘要"的结构，标准模板如下：

--- 'package-a': 'patch:enhance' 'package-b': 'patch:enhance' --- Change summary goes here

3.1 frontmatter 解析

• 键：带引号的包名，如'package-a'、'tauri-bundler'。包名必须与 .changes/config.json 的packages中登记的键一一对应；
• 值：'<bump 类型>:<标签>'的格式。bump 类型取major、minor、patch之一；冒号后是可选的变更标签；
• 可同时列出多个包：一次 PR 若同时影响了多个包，可在 frontmatter 中逐行声明各自的 bump，如上例的package-a与package-b均为patch:enhance。

3.2 变更摘要（Change summary）

• 摘要在---之后以正文形式书写，没有特定的字符数限制；
• 仅限纯文本（text only），不支持 Markdown 渲染；
• 这些摘要会被用于生成 CHANGELOG（README 中提到"the (future implementation of) changelogs"），为变更提供上下文，并在需要更多细节时指向原始 PR。

仓库中 bundler-freebsd-glob-error.md 就是一个教科书式的例子：

--- "tauri-bundler": "patch:bug" --- Make the `Glob` and `GlobPattern` error variants available on all platforms, fixing a compile error in the Windows bundler utilities on targets other than Windows, macOS and Linux.

四、语义化版本：major / minor / patch 的判定标准

变更文件中的 bump 类型严格遵循语义化版本（SemVer）规则。给定版本号MAJOR.MINOR.PATCH，对应递增规则为：

README 同时提示：MAJOR.MINOR.PATCH之外还存在预发布（pre-release）与构建元数据（build metadata）的附加标签，但它们不会在常规流程中直接使用——一旦需要，会在使用前另行讨论，因为合并与发布环节需要额外的处理步骤。

五、变更标签（Change Tags）与分组机制

为了让零散的变更文件在最终 CHANGELOG 中聚合归类，可以在 bump 类型后以:<tag>前缀追加标签：

--- 'package-a': 'patch:enhance' --- Change summary goes here

例如'patch:bug'会把该变更文件与其他同样标注bug标签的变更归为一组。可用标签的完整清单定义在 .changes/config.json 的changeTags键中，共八个：

同时配置了"defaultChangeTag": "changes"——即当开发者未显式指定标签时，变更默认归入"What's Changed"分组。这也解释了为什么仓库中的示例文件bundler-freebsd-glob-error.md将 bump 写成patch:bug（归入 Bug Fixes 组），而非简单写成patch。

六、config.json：covector 的包管理与发布流水线

.changes/config.json 是这套版本管理体系的"控制中枢"，主要包含四部分：

6.1 变更标签（changeTags）

如上一节所列，定义了全部可用标签及其在 CHANGELOG 中的分组标题，另有defaultChangeTag兜底。

6.2 Rust 包管理器（pkgManagers.rust）

定义了 Rust crate 的版本管理流程：

• 版本查询：通过fetch:check调用 crates.io API（https://crates.io/api/v1/crates/${包名}/${版本}）核对已发布版本；
• prepublish：发布前执行cargo install cargo-audit --features=fix，随后运行cargo audit ${ CARGO_AUDIT_OPTIONS || '' }（带--dry-run标记）做供应链安全审计，并在终端输出折叠的 details 块；
• publish：执行cargo publish（dry-run 为cargo publish --dry-run）；
• postpublish：发布后再次fetch:check轮询 crates.io，确认版本确实可见，重试间隔为[5000, 5000, 5000]毫秒。

6.3 JavaScript 包管理器（pkgManagers.javascript）

面向 npm 包的同类流程：

• 版本查询：查询https://registry.npmjs.com/${包名}/${版本}；
• prepublish：pnpm i --frozen-lockfile锁定依赖安装 +pnpm audit安全审计；
• publish：pnpm publish --access public --loglevel debug --no-git-checks（dry-run 用npm publish --dry-run）；
• postpublish：同样以 5 秒间隔最多重试 3 次轮询 npm registry 确认发布成功。

6.4 包清单（packages）

登记了仓库中全部受版本管理的包，以及它们的路径、所属管理器与依赖关系。从源码结构看，该清单与 crates/ 和 packages/ 的实际目录一一对应：

值得注意的是，tauri、tauri-build、tauri-plugin、@tauri-apps/cli等包还配置了postversion钩子，用于在版本提升后同步 CLI 元数据（调用 .scripts/ci/sync-cli-metadata.js 等脚本），tauri包还会额外重新构建 schema 生成器。这些细节印证了 README 中"依赖包会自动被 bump"的设计：依赖关系在 config.json 中显式声明，covector 依据它推导完整的影响面。

七、真实案例：一个变更文件如何落地到源码

以仓库中现存的实际变更文件 bundler-freebsd-glob-error.md 为例，完整追踪一次变更从"变更文件"到"源码修复"的闭环：

变更文件声明：

--- "tauri-bundler": "patch:bug" --- Make the `Glob` and `GlobPattern` error variants available on all platforms, fixing a compile error in the Windows bundler utilities on targets other than Windows, macOS and Linux.

它声明：tauri-bundler包做一次patch级（bug 修复）升级，且该修复属于bug分组。变更摘要点明问题本质——Glob与GlobPattern两个错误变体此前并非在所有平台可用，导致非 Windows/macOS/Linux 目标（如 FreeBSD）上编译 Windows bundler 工具时报错。

源码层面的印证：在 crates/tauri-bundler/src/error.rs 中可以看到 bundler 的错误枚举定义，其中：

/// Invalid glob pattern. #[error("{0}")] GlobPattern(#[from] glob::PatternError), /// Failed to use glob pattern. #[error("`{0}`")] Glob(#[from] glob::GlobError),

这两个变体（error.rs）与其他若干变体一样没有任何#[cfg(...)]平台条件限制，因而在所有平台上均可编译。对比同文件中其他确实受平台限制的变体——如RegexError仅#[cfg(any(target_os = "macos", windows))]、RpmError仅#[cfg(target_os = "linux")]、TimeError/Plist/AppleNotarization仅#[cfg(target_os = "macos")]——可以推断：该变更文件正是描述了一次移除平台条件、使 glob 错误变体全平台可见的修复。当此变更随版本发布后，其摘要最终会以"Bug Fixes"分组写入tauri-bundler的 CHANGELOG（仓库各 crate 的 CHANGELOG 均由此机制生成，例如 crates/tauri-bundler/CHANGELOG.md）。

八、完整工作流总结

结合 README 规范与 config.json 配置，Tauri 仓库一次标准版本变更的完整流程为：

1. 提交 PR 时：开发者对自己实际改动的包，在.changes/下新增一个.md文件；
2. 声明 bump：frontmatter 中写'包名': 'bump类型:标签'，如'tauri-bundler': 'patch:bug'；bump 类型只考虑 semver 语义，标签从changeTags中选取，不指定则落入默认的changes分组；
3. 写摘要：在 frontmatter 之后用纯文本简述变更内容与背景；
4. 发布时：covector 读取全部变更文件，依据packages中的依赖关系推导需要联动升级的包，统一计算新版本号，依次执行各包管理器的prepublish（cargo audit / pnpm audit）、publish（cargo publish / pnpm publish）与postpublish（轮询 crates.io / npm registry 确认），并自动生成 CHANGELOG；
5. 清理：变更文件在发布流程中被消费后，即可从.changes/目录移除。

这套机制的收益在于：版本决策与代码改动解耦、多包依赖联动零人工计算、CHANGELOG 自动生成且有分组语义，是多包仓库（Rust + npm 混合）版本治理中一种轻量而严谨的实践范式。

• 桌面应用
• 跨平台
• 移动开发