cargo-release完全指南：高效管理Rust crate发布流程

cargo-release是Rust生态中一款强大的Cargo子命令工具，专为自动化管理Rust crate发布流程设计。它提供从版本控制、提交管理、标签创建到最终发布的全流程支持，通过灵活的配置系统满足不同项目的发布需求，显著提升开发团队的发布效率。无论是独立crate还是多包工作区，cargo-release都能帮助你实现标准化、自动化的发布流程，减少人为错误并确保发布质量。

基础入门：快速掌握cargo-release

安装与环境准备

要开始使用cargo-release，首先需要通过Cargo安装该工具：

cargo install cargo-release

安装完成后，可通过以下命令验证安装是否成功：

cargo release --version

配置文件优先级规则

cargo-release采用多层次的配置系统，配置来源按优先级从高到低排列如下：

1. 命令行参数（最高优先级）
2. 通过--config PATH指定的配置文件
3. 项目内的Cargo.toml（[package.metadata.release]部分）
4. 项目内的release.toml文件
5. 工作区的Cargo.toml（[workspace.metadata.release]部分）
6. 工作区的release.toml文件
7. 用户级配置文件（如$HOME/.config/cargo-release/release.toml）

这种设计允许你在不同级别设置默认值，并在需要时通过更高优先级的配置覆盖。例如，你可以在工作区级别设置通用规则，然后在特定包中进行个性化调整。

基本使用流程

cargo-release的基本工作流程包括以下几个核心步骤：

1. 检查环境：验证当前分支、工作区状态和配置
2. 版本更新：根据语义化版本规则更新版本号
3. 生成提交：创建版本更新的提交记录
4. 创建标签：为新版本创建git标签
5. 发布到crates.io：执行cargo publish
6. 推送更改：将提交和标签推送到远程仓库

你可以通过单个命令执行完整流程：

cargo release patch --execute

核心功能：自定义你的发布策略

分支控制配置

作用：限制允许执行发布操作的分支，增强代码安全性
取值范围：字符串数组，支持glob模式匹配
实际应用：

默认配置：

allow-branch = ["*", "!HEAD"]

生产环境推荐配置：

allow-branch = ["main", "master", "release/*"]

这个配置确保只有在指定的分支上才能执行发布操作，防止从开发分支或功能分支意外发布。

签名与提交配置

作用：控制提交和标签的GPG签名以及提交消息格式
取值范围：

• sign-commit: 布尔值（true/false）
• sign-tag: 布尔值（true/false）
• pre-release-commit-message: 字符串，支持占位符

实际应用：

安全发布配置：

sign-commit = true
sign-tag = true
pre-release-commit-message = "chore: Release {{crate_name}} v{{version}}"

常用占位符包括：

• {{crate_name}}: 当前crate名称
• {{version}}: 新版本号
• {{date}}: 发布日期
• {{previous_version}}: 上一版本号

版本管理策略

作用：控制工作区版本同步和依赖版本更新规则
取值范围：

• shared-version: 布尔值或字符串（版本组名称）
• dependent-version: "upgrade" | "fix" | "patch" | "minor" | "major" | "error"

实际应用：

单包项目配置：

shared-version = false
dependent-version = "upgrade"

多包工作区同步版本配置：

shared-version = true
dependent-version = "patch"

版本组配置：

shared-version = "api-v2"

发布流程控制

作用：配置发布过程中的关键行为
取值范围：

• publish: 布尔值（是否执行cargo publish）
• registry: 字符串（crates.io registry地址）
• push: 布尔值（是否推送提交和标签）
• push-remote: 字符串（远程仓库名称）

实际应用：

完整发布配置：

publish = true
registry = "crates-io"
push = true
push-remote = "origin"
verify = true
enable-all-features = true

测试发布配置（仅本地验证）：

publish = false
push = false
verify = true

实战案例：配置文件示例与解析

单包项目基础配置

以下是一个适合独立crate项目的基础配置（release.toml）：

# 分支控制
allow-branch = ["main", "master"]

# 签名配置
sign-commit = true
sign-tag = true

# 提交设置
pre-release-commit-message = "chore: Release {{crate_name}} v{{version}}"

# 标签设置
tag = true
tag-name = "v{{version}}"
tag-message = "Release {{tag_name}}"

# 发布设置
publish = true
registry = "crates-io"
verify = true

# 推送设置
push = true
push-remote = "origin"

# 版本替换规则
pre-release-replacements = [
  { file = "CHANGELOG.md", search = "## Unreleased", replace = "## {{version}} - {{date}}" },
  { file = "Cargo.toml", search = "version = \".+\"", replace = "version = \"{{version}}\"" }
]

多包工作区配置

对于工作区项目，推荐在工作区根目录创建release.toml：

# 工作区共享配置
[workspace.metadata.release]
shared-version = true
allow-branch = ["main", "release/*"]
dependent-version = "upgrade"
push = true
push-remote = "origin"
sign-commit = true
sign-tag = true

# 为特定包设置覆盖配置
[package.metadata.release]
# 包特定配置将覆盖工作区默认值
tag-prefix = "{{crate_name}}-"

预发布钩子配置

预发布钩子允许你在发布过程中执行自定义脚本，如生成CHANGELOG或运行额外测试：

pre-release-hook = ["./hook.sh"]

示例hook.sh脚本：

#!/bin/bash
# 生成CHANGELOG
cargo install git-cliff --quiet
git-cliff --tag {{version}} > CHANGELOG.md
git add CHANGELOG.md

# 运行额外测试
cargo test --all-features

高级技巧：优化你的发布流程

环境变量利用技巧

pre-release-hook可以访问多种环境变量，用于编写灵活的发布脚本：

• PREV_VERSION: 上一版本号
• NEW_VERSION: 新版本号
• CRATE_NAME: 当前crate名称
• CRATE_PATH: 当前crate路径
• RELEASE_ROOT: 发布根目录

示例：使用环境变量创建版本特定文件

#!/bin/bash
echo "Released {{CRATE_NAME}} {{NEW_VERSION}} on {{DATE}}" > RELEASE_NOTES.txt

工作区版本管理高级策略

对于复杂工作区，可使用版本组功能实现部分包版本同步：

# 工作区级配置
[workspace.metadata.release]
shared-version = { api = true, cli = true }

# 包A配置
[package.metadata.release]
shared-version = "api"

# 包B配置
[package.metadata.release]
shared-version = "api"

# 包C配置
[package.metadata.release]
shared-version = "cli"

这种配置将包A和B归入"api"版本组，包C归入"cli"版本组，各组内版本保持同步。

自定义版本号生成规则

通过命令行参数结合配置文件，可以实现灵活的版本控制：

# 升级次要版本
cargo release minor --execute

# 升级补丁版本并添加预发布标签
cargo release patch --pre-release beta --execute

# 设置特定版本号
cargo release 2.0.0 --execute

配置诊断：常见问题与最佳实践

常见配置问题排查

问题1：发布时提示"detached HEAD"错误

解决方案：检查allow-branch配置，默认配置["*", "!HEAD"]禁止在分离头指针状态发布。确保你在指定的分支上工作：

git checkout main
cargo release patch --execute

问题2：工作区版本不同步

解决方案：启用shared-version = true或指定版本组，确保所有包使用相同版本号：

shared-version = true
dependent-version = "upgrade"

问题3：预发布钩子执行失败

解决方案：检查钩子脚本权限和返回码，确保脚本具有可执行权限且执行成功：

chmod +x hook.sh
# 测试钩子脚本
./hook.sh

安全发布最佳实践

1. 限制发布分支：仅允许从受保护的主分支或发布分支发布
2. 启用签名验证：配置sign-commit和sign-tag确保提交和标签的完整性
3. 使用预发布钩子：在发布前运行测试、代码检查和文档生成
4. 先进行干运行：使用--dry-run选项验证发布流程，再执行实际发布：

cargo release patch --dry-run
# 验证无误后执行
cargo release patch --execute

5. 版本号管理：严格遵循语义化版本控制（SemVer）规则

总结与资源

cargo-release是Rust项目发布流程的强大工具，通过灵活的配置系统和丰富的功能，帮助开发者实现标准化、自动化的发布流程。无论是简单的单包项目还是复杂的多包工作区，cargo-release都能显著提升发布效率并降低人为错误风险。

官方配置指南：docs/reference.md 官方FAQ：docs/faq.md