语义化版本 ^/~ ​

核心概念 ​

语义化版本(Semantic Versioning,简称 SemVer)是 Rust 生态中依赖管理的基础规则。版本号格式为 MAJOR.MINOR.PATCH(如 1.4.2),每一位的含义是:

  • MAJOR(主版本):不兼容的 API 变更
  • MINOR(次版本):向后兼容的功能新增
  • PATCH(补丁版本):向后兼容的 bug 修复

Cargo 使用两种版本约束符号:^(脱字符,默认)和 ~(波浪号)。^ 允许 SemVer 兼容的更新(不改变最左非零位),~ 只允许补丁级别的更新。理解这两者的区别对依赖管理至关重要。

toml
[dependencies]
# ^ 脱字符(默认,省略时等同于 ^)
serde = "1.0.100"       # 等同于 "^1.0.100",即 >=1.0.100, <2.0.0
rand = "0.8"             # 等同于 "^0.8",即 >=0.8.0, <0.9.0

# ~ 波浪号
log = "~1.0.100"         # >=1.0.100, <1.1.0(只允许 patch 更新)
uuid = "~0.8.2"          # >=0.8.2, <0.9.0

^ 脱字符规则 ​

toml
# ^ 规则:保持最左非零位不变

# 1.x.x 系列:主版本锁定
"^1.2.3"    # >=1.2.3, <2.0.0    可更新到 1.99.99
"^1.2"      # >=1.2.0, <2.0.0
"^1"        # >=1.0.0, <2.0.0

# 0.x.x 系列:次版本锁定(更严格)
"^0.2.3"    # >=0.2.3, <0.3.0    最左非零位是 0.2
"^0.2"      # >=0.2.0, <0.3.0
"^0.0.3"    # >=0.0.3, <0.0.4    最左非零位是 0.0.3
"^0.0"      # >=0.0.0, <0.1.0
"^0"        # >=0.0.0, <1.0.0
写法等价范围允许的更新
^1.2.3>=1.2.3, <2.0.0minor + patch
^0.2.3>=0.2.3, <0.3.0仅 patch
^0.0.3>=0.0.3, <0.0.4无更新
^1.0>=1.0.0, <2.0.0minor + patch
^0.0>=0.0.0, <0.1.0仅 patch

~ 波浪号规则 ​

toml
# ~ 规则:只允许补丁级别的更新
# 如果指定了 minor 版本,锁定 minor
# 如果只指定了 major,允许 minor 更新

"~1.2.3"    # >=1.2.3, <1.3.0    锁定 1.2.x
"~1.2"      # >=1.2.0, <1.3.0    锁定 1.2.x
"~1"        # >=1.0.0, <2.0.0    锁定 1.x(同 ^1)

"~0.2.3"    # >=0.2.3, <0.3.0    锁定 0.2.x
"~0.2"      # >=0.2.0, <0.3.0    锁定 0.2.x
写法等价范围允许的更新
~1.2.3>=1.2.3, <1.3.0仅 patch
~0.2.3>=0.2.3, <0.3.0仅 patch
~1>=1.0.0, <2.0.0minor + patch

^ 与 ~ 的对比 ​

场景^(默认)~
1.2.3<2.0.0<1.3.0
0.2.3<0.3.0<0.3.0
0.0.3<0.0.4<0.0.4
1.2<2.0.0<1.3.0
更新范围较宽较窄
适合场景一般依赖需要保守更新

其他版本指定方式 ​

toml
[dependencies]
# 精确版本
serde = "=1.0.193"       # 只允许 1.0.193

# 通配符
log = "0.4.*"            # >=0.4.0, <0.5.0

# 范围组合
num = ">=1.0.0, <2.0.0"
bytes = ">=1.5"

# 多个约束用逗号分隔
complex = ">=1.0, <1.5"

0.x 版本的特殊性 ​

toml
# 0.x 版本表示 API 尚不稳定
# ^ 在 0.x 下的行为比 1.x 严格得多

# 1.x 下:^ 允许 minor 和 patch 更新
"^1.0.0"    # >=1.0.0, <2.0.0   — 很宽松

# 0.x 下:^ 只允许 patch 更新
"^0.2.0"    # >=0.2.0, <0.3.0   — 较严格

# 0.0.x 下:^ 几乎不允许更新
"^0.0.3"    # >=0.0.3, <0.0.4   — 非常严格

# 这是因为 SemVer 规定 0.x 版本不保证 API 稳定
# 所以 0.2 → 0.3 可能有破坏性变更

基本示例 ​

toml
# 一个实际项目中的版本管理

[dependencies]
# 稳定的大版本依赖,用 ^ 允许宽松更新
serde = "1"               # ^1.0.0 — 自动获取 1.x 的最新版
tokio = "1"               # ^1.0.0 — 自动获取 1.x 的最新版

# 需要特定功能的版本
axum = "0.7"              # ^0.7.0 — 0.7.x 的最新版
sqlx = "0.7"              # ^0.7.0 — 0.7.x 的最新版

# 保守更新策略
openssl = "~0.10.60"      # >=0.10.60, <0.11.0 — 只接受 patch

# 需要精确版本(罕见)
niche-crate = "=0.3.1"    # 只用这个版本
rust
fn main() {
    // 查看依赖版本的命令:
    // cargo tree              — 查看完整依赖树
    // cargo tree -d           — 查看重复依赖
    // cargo update            — 在约束范围内更新到最新
    // cargo update -p serde   — 只更新 serde

    println!("语义化版本让依赖更新安全且可预测");
}

常见问题 ​

问题一:写 "1" 和 "1.0" 和 "1.0.0" 有区别吗?

在 ^ 规则下没有实质区别,都表示 >=1.0.0, <2.0.0。但 "1.0.0" 更明确地表示你测试过的最低版本是 1.0.0。建议至少写到 minor 版本,如 "1.0"。

问题二:什么时候用 ~ 而不是 ^?

当你需要保守的更新策略时用 ~。比如依赖一个行为可能在 minor 版本中微妙变化的 crate,或者在生产环境中需要更严格的版本控制。大多数情况下用默认的 ^ 即可。

问题三:为什么 0.x 版本的 ^ 行为不同?

SemVer 规定 0.x 版本不保证 API 稳定,任何 minor 版本都可能有破坏性变更。所以 Cargo 对 0.x 的 ^ 更严格:^0.2.3 只允许 0.2.x 的 patch 更新,而不是 0.x 的所有版本。

问题四:Cargo.lock 和版本约束的关系?

Cargo.toml 声明版本范围,Cargo.lock 记录实际选择的精确版本。cargo build 首次运行时确定精确版本并写入 Cargo.lock,之后每次构建都使用锁定的版本。cargo update 在约束范围内更新。

适用场景 ​

  • 一般依赖:使用默认的 ^,获得兼容更新
  • 保守策略:使用 ~,只接受 patch 更新
  • 锁定版本:使用 =,固定精确版本
  • 版本范围:使用 >=, < 组合指定范围

注意事项 ​

  • 省略 ^ 等同于显式写 ^
  • 0.x 版本下 ^ 的行为比 1.x 严格
  • ~ 总是只允许 patch 更新(当指定了 minor 时)
  • 不建议使用 * 通配符,影响可重复构建
  • Cargo.lock 锁定精确版本,cargo update 更新
  • 库项目建议指定宽松的版本范围,应用项目可以更精确

总结 ​

语义化版本是 Cargo 依赖管理的基础,版本号格式为 MAJOR.MINOR.PATCH。^(默认,可省略)保持最左非零位不变,允许兼容更新:^1.2.3 允许到 <2.0.0,^0.2.3 允许到 <0.3.0。~ 只允许 patch 更新:~1.2.3 允许到 <1.3.0。0.x 版本下 ^ 的行为更严格,因为 SemVer 规定 0.x 不保证 API 稳定。大多数项目使用默认的 ^ 即可,需要保守策略时用 ~,极端情况用 = 锁定精确版本。