虚拟清单
核心概念
虚拟清单(virtual manifest)是一种特殊的 Cargo.toml,它只包含 [workspace] 段而不包含 [package] 段。也就是说,workspace 根目录本身不是一个 crate,它只负责组织和管理子 crate。这与"普通 workspace"不同——普通 workspace 的根 Cargo.toml 既是 workspace 配置又是一个 package 定义。
虚拟清单是组织大型多 crate 项目的推荐方式,因为它让根目录的职责更清晰:只管理 workspace,不包含任何业务代码。
# === 虚拟清单(根目录没有 [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/ 目录# === 非虚拟清单(根目录既是 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基本示例
# Cargo.toml(虚拟清单)
[workspace]
members = ["app", "lib"]
resolver = "2"
[workspace.package]
edition = "2024"
license = "MIT"
[workspace.dependencies]
serde = { version = "1", features = ["derive"] }# lib/Cargo.toml
[package]
name = "shared-lib"
version = "0.1.0"
edition.workspace = true
[dependencies]
serde = { workspace = true }# app/Cargo.toml
[package]
name = "my-app"
version = "0.1.0"
edition.workspace = true
[dependencies]
shared-lib = { path = "../lib" }
serde = { workspace = true }// lib/src/lib.rs
use serde::{Serialize, Deserialize};
#[derive(Debug, Serialize, Deserialize)]
pub struct Item {
pub name: String,
pub count: u32,
}// 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);
}常见命令
# 虚拟清单下的常用命令
# 编译所有成员
# 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 可以设置默认操作目标。