workspace 依赖继承
核心概念
Workspace 依赖继承(Rust 1.64 稳定)允许在 workspace 根目录的 Cargo.toml 中统一声明依赖版本,成员 crate 通过 workspace = true 继承这些配置。这解决了多 crate 项目中依赖版本不一致的问题——不再需要在每个成员的 Cargo.toml 中重复写同一个依赖的版本号。
继承通过 [workspace.dependencies] 段定义,成员通过 dep = { workspace = true } 引用。成员可以在继承的基础上额外添加 features,但不能覆盖版本号。
# === 根 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"# === 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 }继承的语法
# === 根 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 字段
# 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 | 作者列表 |
edition | Rust edition |
rust-version | 最低 Rust 版本 |
license | 开源协议 |
repository | 仓库地址 |
homepage | 主页 |
description | 描述(不常继承) |
publish | 发布控制 |
exclude / include | 发布文件控制 |
基本示例
# 根 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"# crates/core/Cargo.toml
[package]
name = "my-core"
version.workspace = true
edition.workspace = true
license.workspace = true
[dependencies]
serde = { workspace = true }
thiserror = { workspace = true }# 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 }// 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 项目中依赖版本不一致和重复配置的问题,修改根配置即可批量更新所有成员。