Cargo workspace 版本发布多包项目别手动改到手酸一、多包版本很容易乱Cargo workspace 很适合组织多个 crate核心库、CLI、插件 SDK、测试工具。但包一多版本发布就容易乱。某个内部 crate 升级了依赖它的 CLI 忘记改CHANGELOG 写了Cargo.toml 没改tag 打了包没发。多包项目需要发布流程而不是手工记忆。之前参与的项目有四个 cratecore、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 --workspacecargo 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记录这次发布从准备到验证的步骤。新人接手或隔几个月再发布时不会再靠记忆翻命令。
