虚拟清单 ​

核心概念 ​

虚拟清单(virtual manifest)是一种特殊的 Cargo.toml,它只包含 [workspace] 段而不包含 [package] 段。也就是说,workspace 根目录本身不是一个 crate,它只负责组织和管理子 crate。这与"普通 workspace"不同——普通 workspace 的根 Cargo.toml 既是 workspace 配置又是一个 package 定义。

虚拟清单是组织大型多 crate 项目的推荐方式,因为它让根目录的职责更清晰:只管理 workspace,不包含任何业务代码。

toml
# === 虚拟清单(根目录没有 [package])===
[workspace]
members = [
    "crates/core",
    "crates/cli",
    "crates/server",
]
resolver = "2"

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

# 注意:没有 [package] 段
# 根目录没有 src/ 目录
toml
# === 非虚拟清单(根目录既是 workspace 又是 package)===
[package]
name = "my-root-crate"
version = "0.1.0"
edition = "2024"

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

[dependencies]
serde = "1"

虚拟清单 vs 非虚拟清单 ​

特性虚拟清单非虚拟清单
[package] 段没有有
根目录是 crate不是是
根目录有 src/没有有
职责只管理 workspace同时是 package 和 workspace
适合场景大型多 crate 项目主 crate + 辅助 crate
cargo build 在根目录需要 -p 或 --workspace默认编译根 crate

目录结构 ​

# 虚拟清单的典型目录结构
my-project/
├── Cargo.toml           # 虚拟清单(只有 [workspace])
├── Cargo.lock           # 共享锁文件
├── README.md
├── crates/
│   ├── core/
│   │   ├── Cargo.toml   # [package] name = "my-core"
│   │   └── src/
│   │       └── lib.rs
│   ├── cli/
│   │   ├── Cargo.toml   # [package] name = "my-cli"
│   │   └── src/
│   │       └── main.rs
│   └── server/
│       ├── Cargo.toml   # [package] name = "my-server"
│       └── src/
│           └── main.rs

基本示例 ​

toml
# Cargo.toml(虚拟清单)
[workspace]
members = ["app", "lib"]
resolver = "2"

[workspace.package]
edition = "2024"
license = "MIT"

[workspace.dependencies]
serde = { version = "1", features = ["derive"] }
toml
# lib/Cargo.toml
[package]
name = "shared-lib"
version = "0.1.0"
edition.workspace = true

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

[dependencies]
shared-lib = { path = "../lib" }
serde = { workspace = true }
rust
// lib/src/lib.rs
use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize)]
pub struct Item {
    pub name: String,
    pub count: u32,
}
rust
// app/src/main.rs
use shared_lib::Item;

fn main() {
    let item = Item {
        name: "widget".to_string(),
        count: 42,
    };
    println!("{:?}", item);

    let json = serde_json::to_string(&item).unwrap_or_default();
    println!("JSON: {}", json);
}

常见命令 ​

bash
# 虚拟清单下的常用命令

# 编译所有成员
# cargo build --workspace

# 编译特定成员
# cargo build -p my-cli

# 运行特定的 binary
# cargo run -p my-cli

# 测试所有成员
# cargo test --workspace

# 在根目录直接 cargo build 会提示需要 -p 或 --workspace
# 因为根目录本身不是一个 package

常见问题 ​

问题一:虚拟清单下直接运行 cargo build 会怎样?

如果没有设置 default-members,Cargo 会编译所有 workspace 成员。设置了 default-members 后,默认只编译指定的成员。

问题二:虚拟清单可以有 [dependencies] 吗?

不能有 [dependencies],因为没有 [package]。但可以有 [workspace.dependencies] 用于依赖继承。

问题三:什么时候用虚拟清单,什么时候用非虚拟清单?

如果项目有一个明确的"主 crate"且其他 crate 是辅助的,用非虚拟清单。如果项目是多个平等的 crate 组合(如微服务),用虚拟清单。大型项目推荐虚拟清单。

问题四:虚拟清单的根目录可以有 build.rs 吗?

不能。build.rs 属于 package,虚拟清单没有 package,所以不能有构建脚本。每个成员 crate 可以有自己的 build.rs。

适用场景 ​

  • 大型 monorepo:多个独立的服务和库
  • 微服务架构:每个服务是一个独立 crate
  • 框架项目:核心库 + 工具 + 示例 + 测试
  • 清晰的职责分离:根目录只管理,不包含代码

注意事项 ​

  • 虚拟清单不能有 [package]、[dependencies]、[[bin]] 等段
  • 可以有 [workspace.dependencies] 和 [workspace.package]
  • 根目录不需要 src/ 目录
  • 需要用 -p 或 --workspace 指定操作目标
  • default-members 可以设置默认操作的成员
  • 共享 Cargo.lock 和 target/

总结 ​

虚拟清单是只包含 [workspace] 段而没有 [package] 段的 Cargo.toml,根目录本身不是一个 crate,只负责组织管理子 crate。这种方式让项目结构更清晰,适合大型多 crate 项目。虚拟清单可以使用 [workspace.dependencies] 和 [workspace.package] 进行依赖和元数据继承。在根目录运行 Cargo 命令需要用 -p 指定成员或 --workspace 操作所有成员。default-members 可以设置默认操作目标。