workspace 工作空间
核心概念
Workspace(工作空间)是 Cargo 管理多个相关 crate 的机制。一个 workspace 由多个包(package)组成,它们共享同一个 Cargo.lock 文件、同一个 target/ 输出目录,以及统一的依赖版本解析。Workspace 适合将大型项目拆分为多个独立的 crate,每个 crate 有自己的 Cargo.toml,但通过 workspace 协调构建。
Workspace 的根目录有一个 Cargo.toml,其中包含 [workspace] 段来声明成员列表。成员可以是库、可执行文件、过程宏 crate 等任意类型。
# 根目录的 Cargo.toml
[workspace]
members = [
"crates/core", # 核心库
"crates/utils", # 工具库
"crates/macros", # 过程宏
"crates/cli", # 命令行工具
"crates/server", # 服务器
]
resolver = "2" # 推荐使用 v2 解析器# 典型的 workspace 目录结构
my-project/
├── Cargo.toml # workspace 根配置
├── Cargo.lock # 共享的锁文件
├── target/ # 共享的构建目录
├── crates/
│ ├── core/
│ │ ├── Cargo.toml
│ │ └── src/lib.rs
│ ├── utils/
│ │ ├── Cargo.toml
│ │ └── src/lib.rs
│ ├── macros/
│ │ ├── Cargo.toml
│ │ └── src/lib.rs
│ ├── cli/
│ │ ├── Cargo.toml
│ │ └── src/main.rs
│ └── server/
│ ├── Cargo.toml
│ └── src/main.rsworkspace 配置选项
[workspace]
# members:显式列出成员
members = [
"crates/*", # 通配符匹配
"apps/server",
]
# exclude:排除某些路径
exclude = [
"crates/experimental", # 不包含在 workspace 中
]
# resolver:依赖解析器版本
resolver = "2" # v2 解析器(2021 edition 默认)
# v2 对 features 的解析更精确
# default-members:cargo 命令默认操作的成员
default-members = ["crates/cli"]
# 在根目录执行 cargo run 时,默认运行 cli成员之间的依赖
# crates/cli/Cargo.toml
[package]
name = "my-cli"
version = "0.1.0"
edition = "2024"
[dependencies]
# 通过路径引用 workspace 中的其他成员
my-core = { path = "../core" }
my-utils = { path = "../utils" }
my-macros = { path = "../macros" }// crates/cli/src/main.rs
// 使用 workspace 中的其他 crate
use my_core::Config;
use my_utils::format_output;
fn main() {
let config = Config::default();
println!("{}", format_output(&config));
}workspace 的优势
| 优势 | 说明 |
|---|---|
| 共享 Cargo.lock | 所有成员使用相同的依赖版本 |
| 共享 target/ | 避免重复编译,节省磁盘空间 |
| 统一构建 | cargo build --workspace 编译所有成员 |
| 统一测试 | cargo test --workspace 测试所有成员 |
| 依赖一致性 | 所有成员对同一 crate 使用相同版本 |
| 代码复用 | 成员之间通过路径依赖互相引用 |
基本示例
# 根 Cargo.toml
[workspace]
members = ["app", "lib"]
resolver = "2"# lib/Cargo.toml
[package]
name = "my-lib"
version = "0.1.0"
edition = "2024"
[dependencies]
serde = { version = "1", features = ["derive"] }// lib/src/lib.rs
use serde::{Serialize, Deserialize};
#[derive(Debug, Serialize, Deserialize)]
pub struct Message {
pub text: String,
pub priority: u8,
}
impl Message {
pub fn new(text: &str, priority: u8) -> Self {
Message {
text: text.to_string(),
priority,
}
}
}# app/Cargo.toml
[package]
name = "my-app"
version = "0.1.0"
edition = "2024"
[dependencies]
my-lib = { path = "../lib" }// app/src/main.rs
use my_lib::Message;
fn main() {
let msg = Message::new("workspace 运行正常", 1);
println!("{:?}", msg);
}常用命令
# 构建所有成员
# cargo build --workspace
# 测试所有成员
# cargo test --workspace
# 只构建特定成员
# cargo build -p my-cli
# 运行特定 binary
# cargo run -p my-cli
# 检查所有成员
# cargo check --workspace
# 格式化所有成员
# cargo fmt --all
# Clippy 检查所有成员
# cargo clippy --workspace常见问题
问题一:workspace 成员可以有不同的 edition 吗?
可以。每个成员的 Cargo.toml 可以独立设置 edition。workspace 中可以混合使用 2018、2021、2024 等不同 edition 的 crate。
问题二:workspace 中的 crate 可以独立发布吗?
可以。每个成员都是独立的包,可以单独发布到 crates.io。发布时路径依赖需要同时指定 version,如 my-core = { path = "../core", version = "0.1" }。
问题三:在子目录运行 cargo 命令会怎样?
在 workspace 成员目录中运行 cargo build,Cargo 会自动检测到 workspace 并使用根目录的 Cargo.lock 和 target/。只有当前 crate 及其依赖会被编译。
问题四:workspace 的 Cargo.lock 应该提交到版本控制吗?
如果 workspace 包含应用程序(bin crate),应该提交。如果全是库 crate,通常不提交。
适用场景
- 大型项目拆分:将单体项目分解为多个独立模块
- monorepo 管理:一个仓库包含多个相关的 crate
- 共享基础设施:多个应用共用核心库和工具
- 微服务架构:多个服务共享通用代码
注意事项
- workspace 成员共享
Cargo.lock和target/ - 推荐使用
resolver = "2" - 成员之间通过
path依赖互相引用 default-members控制默认操作的成员- 根
Cargo.toml可以同时是 workspace 和 package - 通配符
members = ["crates/*"]可以简化成员列表
总结
Workspace 是 Cargo 管理多 crate 项目的机制,成员共享 Cargo.lock、target/ 和统一的依赖版本解析。根目录的 Cargo.toml 通过 [workspace] 段声明成员列表,成员之间通过路径依赖互相引用。cargo build --workspace 编译所有成员,-p 参数指定操作特定成员。每个成员可以有独立的 edition 和配置,也可以单独发布到 crates.io。推荐使用 resolver = "2" 获得更精确的 features 解析。