workspace 依赖继承 ​

核心概念 ​

Workspace 依赖继承(Rust 1.64 稳定)允许在 workspace 根目录的 Cargo.toml 中统一声明依赖版本,成员 crate 通过 workspace = true 继承这些配置。这解决了多 crate 项目中依赖版本不一致的问题——不再需要在每个成员的 Cargo.toml 中重复写同一个依赖的版本号。

继承通过 [workspace.dependencies] 段定义,成员通过 dep = { workspace = true } 引用。成员可以在继承的基础上额外添加 features,但不能覆盖版本号。

toml
# === 根 Cargo.toml ===
[workspace]
members = ["crates/*"]

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
anyhow = "1"
tracing = "0.1"
toml
# === crates/app/Cargo.toml ===
[package]
name = "my-app"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { workspace = true }           # 继承版本和 features
serde_json = { workspace = true }     # 继承版本
tokio = { workspace = true }           # 继承版本和 features
anyhow = { workspace = true }

继承的语法 ​

toml
# === 根 Cargo.toml 定义 ===
[workspace.dependencies]
# 可以定义所有标准的依赖选项
serde = { version = "1", features = ["derive"] }
my-core = { path = "crates/core", version = "0.1" }
my-lib = { git = "https://github.com/user/lib", branch = "main" }
log = "0.4"
tokio = { version = "1", default-features = false }

# === 成员 Cargo.toml 继承 ===
[dependencies]
# 基本继承
serde = { workspace = true }
log = { workspace = true }

# 继承并添加额外 features
tokio = { workspace = true, features = ["rt", "macros"] }

# 继承用于 dev-dependencies
[dev-dependencies]
tokio = { workspace = true, features = ["test-util"] }

可继承的 package 字段 ​

toml
# workspace 还可以继承 package 级别的字段

# === 根 Cargo.toml ===
[workspace.package]
version = "0.1.0"
authors = ["Team <team@example.com>"]
edition = "2024"
rust-version = "1.80"
license = "MIT"
repository = "https://github.com/org/project"

# === 成员 Cargo.toml ===
[package]
name = "my-crate"
version.workspace = true        # 继承版本号
authors.workspace = true        # 继承作者
edition.workspace = true        # 继承 edition
license.workspace = true        # 继承协议
repository.workspace = true     # 继承仓库
可继承字段说明
version版本号
authors作者列表
editionRust edition
rust-version最低 Rust 版本
license开源协议
repository仓库地址
homepage主页
description描述(不常继承)
publish发布控制
exclude / include发布文件控制

基本示例 ​

toml
# 根 Cargo.toml — 完整的 workspace 依赖继承配置

[workspace]
members = ["crates/*"]
resolver = "2"

[workspace.package]
version = "0.2.0"
edition = "2024"
license = "MIT"
repository = "https://github.com/example/project"

[workspace.dependencies]
# 核心依赖
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["full"] }
anyhow = "1"
thiserror = "1"

# 日志
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

# 内部 crate
my-core = { path = "crates/core" }
my-utils = { path = "crates/utils" }

# 测试
pretty_assertions = "1"
tempfile = "3"
toml
# crates/core/Cargo.toml
[package]
name = "my-core"
version.workspace = true
edition.workspace = true
license.workspace = true

[dependencies]
serde = { workspace = true }
thiserror = { workspace = true }
toml
# crates/utils/Cargo.toml
[package]
name = "my-utils"
version.workspace = true
edition.workspace = true

[dependencies]
my-core = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }

[dev-dependencies]
pretty_assertions = { workspace = true }
tempfile = { workspace = true }
rust
// crates/core/src/lib.rs
use serde::{Serialize, Deserialize};
use thiserror::Error;

#[derive(Debug, Error)]
pub enum CoreError {
    #[error("配置错误: {0}")]
    Config(String),
    #[error("IO 错误: {0}")]
    Io(#[from] std::io::Error),
}

#[derive(Debug, Serialize, Deserialize)]
pub struct AppConfig {
    pub name: String,
    pub port: u16,
}

impl Default for AppConfig {
    fn default() -> Self {
        AppConfig {
            name: "my-app".to_string(),
            port: 8080,
        }
    }
}

常见问题 ​

问题一:继承后还能修改 features 吗?

可以在继承的基础上添加 features,但不能移除 workspace 中定义的 features。{ workspace = true, features = ["extra"] } 会合并两边的 features。

问题二:workspace.dependencies 中定义但成员没用的依赖会被编译吗?

不会。[workspace.dependencies] 只是定义了可用的依赖配置,只有成员显式使用 workspace = true 引用的依赖才会被编译。

问题三:能否在继承的同时覆盖版本号?

不能。使用 workspace = true 后,版本号完全由 workspace 控制。如果某个成员需要不同版本,只能不继承,直接指定完整的依赖配置。

问题四:workspace 依赖继承是什么时候稳定的?

Rust 1.64(2022年9月)稳定了 [workspace.dependencies] 和 [workspace.package] 继承功能。

适用场景 ​

  • 统一依赖版本:所有成员使用相同的依赖版本
  • 减少重复配置:版本号只写一次
  • 批量升级:修改根配置即可更新所有成员
  • 统一元数据:version、edition、license 等统一管理

注意事项 ​

  • workspace = true 不能与 version 同时使用
  • 可以在继承基础上额外添加 features
  • 不能移除 workspace 定义中的 features
  • 未被成员引用的 workspace 依赖不会被编译
  • package 字段继承用 field.workspace = true 语法
  • 依赖继承用 dep = { workspace = true } 语法

总结 ​

Workspace 依赖继承(1.64+)通过 [workspace.dependencies] 统一定义依赖版本,成员用 { workspace = true } 继承。还可以通过 [workspace.package] 继承 version、edition、license 等 package 字段。成员可以在继承基础上额外添加 features,但不能覆盖版本号。未被引用的 workspace 依赖不会被编译。这个机制解决了多 crate 项目中依赖版本不一致和重复配置的问题,修改根配置即可批量更新所有成员。