Rust Cargo.toml：清单、依赖与构建配置
更新时间：2026-09-20。Cargo 是 Rust 的官方构建与包管理器，
Cargo.toml是每个 crate 的清单（manifest）。编译模型与 debug/release 实测见 Cargo 与编译模型，国内拉取慢的镜像配置见 cargo 换国内源。
一、一个最小 Cargo.toml
toml
[package]
name = "myapp"
version = "0.1.0"
edition = "2021" # 语言版本，决定语法/ prelude
[dependencies]
serde = "1.0.210" # 等价 "^1.0.210"
rand = { version = "0.8", features = ["small_rng"] }
myutils = { path = "../myutils" } # 本地路径依赖
sha2 = { git = "https://github.com/RustCrypto/hashes.git" } # git 依赖
serde_json = { version = "1", optional = true } # 可选依赖
[features]
default = ["serde_json"]
json = ["dep:serde_json"] # feature 打开可选依赖
[profile.release]
opt-level = 3
lto = true # 链接期优化，产物体积小、运行快但编译慢
codegen-units = 1
strip = true二、依赖版本：脱字符与锁定
| 写法 | 允许范围（SemVer） |
|---|---|
"1.2.3" / "^1.2.3" | >=1.2.3, <2.0.0（不改最左非零位） |
"~1.2" | >=1.2.0, <1.3.0 |
"=1.2.3" | 精确锁定 |
"0.2.3"（^） | >=0.2.3, <0.3.0（0.x 阶段次版本也可能不兼容） |
cargo add serde 可自动写依赖并选最新兼容版本；cargo update 在允许范围内升级 Cargo.lock 记录的具体版本。
三、features：按需编译的能力开关
optional = true的依赖默认不编译；用 feature 绑定后，--features json才引入。- 代码里用
#[cfg(feature = "json")]条件编译，库通过 features 让用户「不为不用的功能付费」。 default是默认开启集合，可用--no-default-features全关再精挑。
四、profile：调编译与产物
| 键 | 作用 |
|---|---|
opt-level | 0/1/2/3/s/z，优化等级（z 最小体积） |
lto | 链接期跨 crate 优化，提速缩体积、显著加编译时间 |
codegen-units = 1 | 牺牲编译速度换更优优化 |
panic = "abort" | panic 直接终止，去掉展开开销 |
strip = true | 去掉符号，缩小二进制 |
dev 用默认 dev profile（零优化 + 调试信息，编译快）；性能/发布基准必须用 --release，否则差距能到几十倍。
五、常用命令
bash
cargo new myapp # 建二进制项目；--lib 建库
cargo add tokio # 加依赖
cargo build # 编译；--release 走 release profile
cargo run # 编译并运行；-- 后接程序参数
cargo test # 跑 #[test]
cargo clippy -- -D warnings# 官方 lint，写代码期就跑
cargo fmt # 统一格式
cargo tree # 看依赖树（排查重复依赖/版本）
cargo bench # 跑 Criterion 等基准六、常见坑
- 用 debug build 跑性能：
opt-level=0慢一个数量级，对比/发布一律--release。 - 0.x 版本当成兼容更新：
^0.2不会升到 0.3，0.y 阶段次版本即可能破坏。 - Cargo.lock 要不要提交：应用/二进制提交（保证可复现构建），库通常不强制。
- feature 相互依赖没声明：A feature 用到可选 crate 却没在 features 里
dep:绑定，编译报错。 - workspace 里各 crate 各自锁版本：根
Cargo.toml用[workspace.dependencies]统一版本。 - 忘记 edition：不写会落到旧版，部分新语法/ trait 解析不同。
总结
Cargo.toml 用 [package] 声明名字/版本/edition、[dependencies] 以版本号（默认 ^SemVer，0.x 下次版本也算不兼容）、git、path 三种方式引依赖，可选依赖配合 [features] 做按需编译，[profile.release] 用 opt-level/lto/codegen-units/strip 换运行性能与体积；日常靠 cargo add/build/run/test/clippy/fmt/tree，性能结论必须 --release 得出，应用要提交 Cargo.lock 锁定可复现构建、库则一般不强制，多 crate 项目用 workspace 统一依赖版本。