workspace 工作空间 ​

核心概念 ​

Workspace(工作空间)是 Cargo 管理多个相关 crate 的机制。一个 workspace 由多个包(package)组成,它们共享同一个 Cargo.lock 文件、同一个 target/ 输出目录,以及统一的依赖版本解析。Workspace 适合将大型项目拆分为多个独立的 crate,每个 crate 有自己的 Cargo.toml,但通过 workspace 协调构建。

Workspace 的根目录有一个 Cargo.toml,其中包含 [workspace] 段来声明成员列表。成员可以是库、可执行文件、过程宏 crate 等任意类型。

toml
# 根目录的 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.rs

workspace 配置选项 ​

toml
[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

成员之间的依赖 ​

toml
# 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" }
rust
// 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 使用相同版本
代码复用成员之间通过路径依赖互相引用

基本示例 ​

toml
# 根 Cargo.toml
[workspace]
members = ["app", "lib"]
resolver = "2"
toml
# lib/Cargo.toml
[package]
name = "my-lib"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { version = "1", features = ["derive"] }
rust
// 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,
        }
    }
}
toml
# app/Cargo.toml
[package]
name = "my-app"
version = "0.1.0"
edition = "2024"

[dependencies]
my-lib = { path = "../lib" }
rust
// app/src/main.rs
use my_lib::Message;

fn main() {
    let msg = Message::new("workspace 运行正常", 1);
    println!("{:?}", msg);
}

常用命令 ​

bash
# 构建所有成员
# 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 解析。