rust中的Cargo.toml文件
Cargo.toml又称清单( manifest )，是 Rust项目的核心配置文件，采用TOML格式（Tom’s Obvious Minimal Language）；定义了一个包（crate）的：
- 名称、版本、作者、许可证；
- 依赖项；
- 编译特性；
- 目标配置；
- 构建脚本；
- 工作区设置等
Cargo.toml vs Cargo.lock
- Cargo.toml：描述依赖的广义信息，由开发者编写
- Cargo.lock：包含依赖的确切信息，由Cargo自动生成，不应手动编辑
| 特性 | Cargo.toml | Cargo.lock |
|---|---|---|
| 作用 | 源配置（声明意图） | 锁定文件（记录实际依赖版本） |
| 手动编辑 | 是（开发者编写 / 修改） | 否（Cargo 自动生成 / 更新） |
| 提交 Git | 需提交 | 库的不需提交；二进制的需提交 |
| 核心内容 | 项目元信息、依赖、构建规则 | 精确的依赖版本树、校验和 |
基础结构
Cargo.toml 按「区段（Section）」组织，每个区段用 [区段名] 标识，核心区段包括：
[package]：定义项目元信息（必选）[dependencies]：生产依赖（必选 / 可选，视项目类型）[dev-dependencies]：开发依赖（测试、文档测试用）[build-dependencies]：构建脚本依赖[lib]：库目标配置[[bin]]：二进制目标配置（支持多个）[profile.*]：构建配置文件（编译优化、调试信息等）[features]：特性开关（条件编译、可选依赖）[workspace]：工作空间配置（多包项目）
示例
[package]
name = "my-rust-app"
version = "0.1.0"
edition = "2024"
description = "A full-featured Rust application"
license = "MIT"
repository = "https://github.com/foo/my-rust-app"
readme = "README.md"
keywords = ["rust", "app", "cli"]
categories = ["command-line-utilities"]
rust-version = "1.75.0"[workspace]
members = ["crates/*", "cli"]
default-members = ["cli"][workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
rand = "0.8"
anyhow = "1.0"[dependencies]
# 工作空间共享依赖
serde = { workspace = true }
rand = { workspace = true }
anyhow = { workspace = true }# 可选依赖（关联特性）
tokio = { version = "1.0", features = ["full"], optional = true }
local-crate = { path = "../local-crate", version = "0.1.0" }
git-crate = { git = "https://github.com/foo/git-crate", tag = "v0.2.0" }# 目标依赖（仅 Windows 平台启用）
[target.'cfg(target_os = "windows")'.dependencies]
winapi = "0.3"# 开发依赖
[dev-dependencies]
rstest = "0.18"
assert-json-diff = "2.0"# 构建脚本依赖（项目根目录有 build.rs）
[build-dependencies]
cc = "1.0"
bindgen = "0.66"# 特性配置
[features]
default = ["tokio", "cli"]
cli = []
advanced = ["cli", "rand/small_rng"]# 二进制目标配置
[[bin]]
name = "my-app"
path = "src/bin/main.rs"
required-features = ["cli"]# 库目标配置
[lib]
name = "my-app-core"
path = "src/lib.rs"
crate_type = ["rlib", "cdylib"]# 构建配置文件
[profile.release]
opt-level = 3
lto = "thin"
strip = "debuginfo"
panic = "abort"
codegen-units = 1[profile.dev]
opt-level = 1
debug = true
incremental = true
package元信息
定义项目的基本信息
| 字段名 | 作用 | 格式 / 要求 | 示例 |
|---|---|---|---|
name | 项目名称（crates.io 唯一） | 字符串：小写字母 + 连字符 | name = "my-rust-project" |
version | 版本号（语义化版本） | 遵循 MAJOR.MINOR.PATCH | version = "0.1.0" |
edition | Rust 版本 edition | 支持 2018/2021/2024 | edition = "2024" |
maintainers | 维护者信息（替代 authors，推荐） | 数组，格式 ["姓名 <邮箱>"] | maintainers = ["Bob <bob@example.com>"] |
description | 项目描述（crates.io 展示） | 字符串，简洁明了（≤100 字符） | description = "A simple Rust utility" |
license | 开源许可证（SPDX 标识符） | 字符串，如 MIT、Apache-2.0、GPL-3.0 | license = "MIT" |
license-file | 自定义许可证文件路径 | 字符串，当 license 无法用 SPDX 标识时使用 | license-file = "LICENSE.txt" |
repository | 代码仓库地址 | 字符串（Git 地址或网页链接） | repository = "https://github.com/foo/bar" |
homepage | 项目主页 | 字符串（HTTP/HTTPS 链接） | homepage = "https://foo.example.com" |
readme | README 文件路径 | 字符串，默认 README.md/README.rst，可省略路径 | readme = "README.md" |
keywords | 搜索关键词（crates.io 用） | 字符串数组，最多 5 个 | keywords = ["rust", "utility", "cli"] |
categories | 分类（crates.io 用） | 字符串数组，需从 官方分类 选择 | categories = ["command-line-utilities"] |
exclude | 构建 / 发布时排除的文件 | 字符串数组（支持 glob 模式） | exclude = ["docs/*", "tests/*.txt"] |
include | 构建 / 发布时强制包含的文件 | 字符串数组（优先级高于 exclude） | include = ["src/**/*", "Cargo.toml"] |
publish | 是否允许发布到 crates.io | 布尔值（true/false） | publish = false（私有项目） |
rust-version | 最低支持的 Rust 版本 | 字符串（如 1.70.0），确保项目在低版本 Rust 上可编译 | rust-version = "1.70.0" |
dependencies普通依赖
定义项目的运行时依赖，支持多种版本约束语法：
| 版本符号 | 含义 | 示例 | 允许的版本范围 |
|---|---|---|---|
^x.y.z | 兼容更新（默认，推荐） | serde = "^1.0.188" | 1.0.188 ≤ 版本 < 2.0.0 |
~x.y.z | 补丁更新（仅允许 PATCH 版本升级） | rand = "~0.8.5" | 0.8.5 ≤ 版本 < 0.9.0 |
>=x.y.z | 最低版本（允许所有更高版本） | tokio = ">=1.20.0" | 1.20.0 及以上 |
=x.y.z | 精确版本（禁止任何升级） | log = "=0.4.20" | 仅 0.4.20 |
* | 任意版本（不推荐，风险高） | foo = "*" | 所有版本 |
依赖支持多种声明方式：
- crates.io：默认，直接指定crate 名称和版本
- git：依赖 Git 仓库中的 crate，支持指定分支、标签、提交哈希
- path：依赖本地 crate，指定本地库的路径
[dependencies]
# 简洁版本约束（等价于 ^1.0）
serde = "1.0"# 明确指定版本约束
rand = "=0.8.5" # 精确版本
tokio = "~1.0" # 允许patch版本更新（1.0 <= version < 1.1）# 使用特性（features）
serde = { version = "1.0", features = ["derive"] }# 依赖来自Git仓库
custom-fork = { git = "https://github.com/user/repo", branch = "fix" }# 本地路径依赖
my-lib = { path = "../my-lib" }
注，其他依赖：
[dev-dependencies]： 仅在cargo test/cargo bench等开发模式下使用[build-dependencies]： 在build.rs文件中使用的依赖[target.'cfg(windows)'.dependencies]/[target.'cfg(unix)'.dependencies]：指定特定平台依赖
Features特性
Features是 Cargo 提供的一种条件编译机制：
- 启用 / 禁用可选依赖
- 控制代码中的条件编译（
cfg(feature = "xxx")） - 组合多个特性（特性继承）
[features]
default = ["tls-rustls"] # 默认启用的特性
tls-rustls = ["rustls", "reqwest-rustls"] # 启用Rustls TLS实现
tls-native = ["native-tls", "reqwest-native"] # 启用系统TLS实现
compression = ["dep:flate2"] # 依赖其他包的特性# 空特性（仅用于条件编译，不关联依赖）
feat1 = []# 特性继承（feat2 启用时，自动启用 feat1 和 "advanced-dep" 依赖）
feat2 = ["feat1", "advanced-dep"]# 关联可选依赖（需先在 [dependencies] 中声明 optional = true）
optional-dep = [] # 与 [dependencies] 中 optional-dep 的 optional = true 对应
advanced-dep = ["dep3"] # 关联 dep3 依赖
说明：
default：默认启用的特性。- 启用时：
cargo build --features "async,json" - 关闭默认特性：
cargo build --no-default-features
在代码中使用特性：
// 仅当 "feat1" 特性启用时编译此模块
#[cfg(feature = "feat1")]
mod feat1_module {// ...
}// 特性启用时执行不同逻辑
fn do_something() {#[cfg(feature = "feat2")]println!("Feat2 is enabled!");#[cfg(not(feature = "feat2"))]println!("Feat2 is disabled!");
}
目标配置
Rust 项目支持两种目标类型：库（lib） 和 二进制可执行文件（bin）
lib库配置
仅当项目是库（或同时是库 + 二进制）时需要，定义库的构建规则
| 字段名 | 作用 | 示例 |
|---|---|---|
name | 库名称（默认与 package.name 一致） | name = "my-lib" |
path | 库源文件路径（默认 src/lib.rs） | path = "src/my_lib.rs" |
crate_type | 生成的库类型（支持多个） | crate_type = ["rlib", "cdylib"] |
crate_name | 编译后的 crate 名称（链接时使用） | crate_name = "my_custom_lib" |
库类型说明：
rlib：Rust 静态库（默认，供 Rust 项目依赖）dylib：Rust 动态库（供 Rust 项目动态链接）cdylib：C 兼容动态库（供 C/C++ 等其他语言调用）staticlib：C 兼容静态库（供其他语言静态链接）proc-macro：过程宏库（仅当项目是过程宏时使用）
bin二进制配置
定义可执行文件的构建规则，[[bin]] 是数组语法（[[ ]]），支持多个二进制目标（一个项目可生成多个可执行文件）
| 字段名 | 作用 | 示例 |
|---|---|---|
name | 可执行文件名称（默认与源文件名称一致） | name = "my-cli" |
path | 源文件路径（默认 src/bin/*.rs） | path = "src/cli/main.rs" |
required-features | 启用该二进制目标所需的特性 | required-features = ["cli"] |
默认约定：
- 单个二进制目标：源文件放在
src/main.rs，无需配置[[bin]] - 多个二进制目标：源文件放在
src/bin/目录下（如src/bin/cli.rs、src/bin/utils.rs），Cargo 自动识别，无需配置[[bin]]（除非需要自定义名称 / 路径）
# 自定义单个二进制目标（源文件不是 src/main.rs）
[[bin]]
name = "my-cli"
path = "src/custom_main.rs"# 多个二进制目标（自定义名称和路径）
[[bin]]
name = "cli"
path = "src/cli.rs"[[bin]]
name = "daemon"
path = "src/daemon.rs"
required-features = ["daemon"] # 仅当启用 "daemon" 特性时才构建
profile.*构建配置
控制编译优化、调试信息、代码生成等规则，Cargo 提供 5 个默认配置文件；
| 配置文件 | 用途 | 默认优化级别 | 适用场景 |
|---|---|---|---|
dev | 开发模式（cargo build 默认） | opt-level = 0（无优化） | 本地开发、调试（编译快） |
release | 发布模式（cargo build --release） | opt-level = 3（全优化） | 生产环境（运行快，编译慢） |
test | 测试模式（cargo test 默认） | opt-level = 0 | 运行测试（兼顾编译速度） |
bench | 基准测试模式（cargo bench） | opt-level = 3 | 性能测试（需要最优性能） |
doc | 文档模式（cargo doc） | opt-level = 0 | 生成文档（编译依赖快） |
可配置字段（常用），参数细节参见《Rust编译参数与优化控制》Profile部分。
| 字段名 | 作用 | 取值范围 / 说明 |
|---|---|---|
opt-level | 优化级别 | 0（无优化）、1（基础优化）、2（中等优化）、3（全优化）、s（代码体积优化）、z（极致体积优化） |
debug | 是否生成调试信息 | true/false（dev 默认为 true，release 默认为 false） |
debug-assertions | 是否启用调试断言（如 debug_assert!） | true/false（dev 默认为 true，release 默认为 false） |
strip | 是否剥离符号信息（减小二进制体积） | “none”（不剥离）、“debuginfo”（仅剥离调试信息）、“all”（剥离所有符号） |
lto | 链接时优化（LTO，提升性能 / 减小体积） | false（禁用）、true（全 LTO）、“thin”（增量 LTO，编译更快） |
codegen-units | 代码生成单元数量（影响编译速度 / 优化） | 整数（默认 dev=256，release=16；值越小优化越好，但编译越慢） |
panic | panic 处理方式 | “unwind”（默认，栈展开，支持 catch_unwind）、“abort”（直接终止进程，体积更小） |
incremental | 是否启用增量编译（加速二次编译） | true/false（dev 默认为 true，release 默认为 false） |
workspace工作区
当项目包含多个 crate（如核心库、CLI 工具、测试工具）时，用工作空间统一管理依赖和构建。
工作区配置
# 工作空间根目录的 Cargo.toml
[workspace]
# 包含的子包（支持 glob 模式）
members = ["crates/*", # 所有 crates 目录下的子包"cli", # 单个子包
]# 默认构建的子包（cargo build 时默认构建这些）
default-members = ["crates/core", "cli"]# 工作空间共享依赖版本（子包可直接引用，避免版本重复）
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
rand = "0.8"
子包中引用工作区依赖
# 子包（crates/core/Cargo.toml）
[dependencies]
# 直接引用工作空间定义的依赖版本
serde = { workspace = true }
rand = { workspace = true, features = ["small_rng"] } # 追加特性