Cargo workspace 版本发布：多包项目别手动改到手酸

Cargo workspace 版本发布：多包项目别手动改到手酸

一、多包版本很容易乱

Cargo workspace 很适合组织多个 crate：核心库、CLI、插件 SDK、测试工具。但包一多，版本发布就容易乱。某个内部 crate 升级了，依赖它的 CLI 忘记改；CHANGELOG 写了，Cargo.toml 没改；tag 打了，包没发。

多包项目需要发布流程，而不是手工记忆。

之前参与的项目有四个 crate：core、cli、sdk、wasm-plugin。有一次 core 改了接口后只发布了 core 的新版本，cli 还在用旧版本号但代码已经引了新类型。发布的 cli 二进制报错说找不到新增的结构体字段，排查半天才定位到版本没同步。

二、先梳理包关系

flowchart TD A[core] --> B[cli] A --> C[sdk] C --> D[wasm-plugin]

发布前要知道哪些包是公开 API，哪些只是内部工具。公开包的版本变化要更谨慎，内部包可以跟随 workspace 统一版本。

[workspace] members = ["crates/core", "crates/cli", "crates/sdk"] [workspace.package] edition = "2021"

共享字段放到 workspace，可以减少重复。

小技巧：workspace 级别的edition、version、authors可以统一管理，但description和documentation应该每个 crate 单独写，因为这些字段会显示在 crates.io 页面上。

三、版本策略要明确

如果所有包一起发布，可以使用统一版本；如果包独立演进，就要记录依赖版本和兼容范围。两种方式都可以，怕的是混着来。

实战踩坑：用统一版本发布时，sdK 有一个 patch 修复但被 cli 的破坏性更新挡住了，因为版本号是一起的。后来把 SDK 拆成了独立版本，CLI 和 SDK 各走各的发布节奏。代价是增加了 changelog 维护量，但不再互相阻塞。

release_policy: versioning: unified changelog_required: true tag_format: v{version} publish_order_checked: true

发布顺序也重要。被依赖的库要先发布，CLI 或插件再发布。

四、发布前跑完整检查

发布不是cargo publish一条命令。至少要跑格式化、lint、测试、文档构建和包内容检查。

cargo fmt --check cargo clippy --workspace --all-targets -- -D warnings cargo test --workspace cargo package --workspace

cargo package能提前发现缺文件、README 路径错误、许可证缺失等问题。

边界场景：有一次 CI 里cargo test全绿就直接 publish 了，结果用户反映安装后样例代码编译不过。原因是 examples 目录依赖 dev-dependencies，但发布包里没包含 example 文件。后来把cargo package --workspace也加进发布检查，缺文件的包直接拒绝发布。

最后，自动化不等于盲发。发布脚本可以减少重复劳动，但版本号、破坏性变更和 changelog 仍要人工确认。工具帮你按流程走，人负责判断这次发布意味着什么。

还要检查 workspace 里的 path 依赖。发布到 crates.io 前，内部 path 依赖需要有对应 version，否则包发布后别人无法解析。cargo package能发现一部分问题，但发布流程里最好显式检查。

my-core = { path = "../core", version = "0.3.0" }

CHANGELOG 也要按包组织。用户关心 CLI 增加了什么命令，库用户关心 API 是否破坏，插件作者关心协议是否变化。一个总 changelog 可以有，但每个公开包最好有清晰条目。

发布后还要做安装验证。新建一个临时目录，从 registry 安装 CLI 或依赖库，确认用户视角能正常使用。很多发布问题只有脱离本地 workspace 才会暴露。

最后，tag 和源码要对应。发布完成后用 tag 锁住版本，后续排查某个用户反馈时，才能回到准确代码。

如果项目包含二进制 CLI，还要确认安装包和源码 crate 的版本一致。用户通过cargo install安装的是发布产物，不是本地 workspace。发布后跑一次真实安装命令，能发现很多路径和 feature 问题。

五、总结

Cargo workspace 版本发布要梳理包关系、选择版本策略、检查发布顺序，并在发布前跑完整质量门槛。

多包项目别手动改到手酸。流程清楚，版本才不会乱。

一个省力做法是把发布检查写成脚本或 CI 步骤，内容包括：包依赖是否有 path 只有没 version、changelog 是否更新、tag 是否和 version 一致。每次发布跑一遍，花几分钟，远好过发布后发现遗漏再打补丁。

另外建议在 workspace 根目录放一个 RELEASING.md，记录这次发布从准备到验证的步骤。新人接手或隔几个月再发布时，不会再靠记忆翻命令。