用 Cargo 管理 Rust 工作区、特性开关…

在 Rust 项目中配置 Cargo 工作区、feature flags、build.rs、增量构建与依赖审计时使用。

适用场景

解决思路

1. 工作区结构：根目录放 Cargo.toml 与唯一的 Cargo.lock，成员 crate 放在 crates/ 或 tools/ 子目录中，各自拥有 Cargo.toml。
2. 根 Cargo.toml 中配置 [workspace] members 列出所有成员路径，并设置 resolver = "2"（edition 2021 必需，防止 dev-dependencies 与普通依赖之间的特性泄漏）。
3. 在 [workspace.dependencies] 中集中声明共享依赖版本（如 serde、tokio、anyhow），成员 crate 用 serde.workspace = true 继承；用 version.workspace = true、edition.workspace = true 继承包元数据。
4. 在根 Cargo.toml 的 [profile.release] 中统一设置 lto = "thin"、codegen-units = 1 等发布配置。
5. Feature flags：在 [features] 中定义 default、简单开关（如 std = []）、组合特性（full = ["std", "async", "serde-support"]），以及用 dep:tokio 语法启用可选依赖（async = ["dep:tokio"]），避免隐式创建特性。
6. 构建时用 cargo build --features "async,serde-support"、--no-default-features、--all-features 切换特性；用 cargo check --no-default-features 与 --all-features 验证特性组合。
7. 注意特性是可加的：一旦在依赖图中被启用就会保持启用；使用 resolver = "2" 防止特性泄漏。
8. build.rs 放在 crate 根目录，在编译前运行；用 println!("cargo:rerun-if-changed=...") 和 cargo:rerun-if-env-changed=VAR 控制重跑条件。
9. build.rs 中可用指令：cargo:rustc-link-lib=NAME 链接库、cargo:rustc-link-search=PATH 添加搜索路径、cargo:rustc-cfg=FLAG 启用 #[cfg(FLAG)]、cargo:rustc-env=KEY=VAL 设置编译期环境变量、cargo:warning=MSG 输出警告。
10. 在 build.rs 中读取 TARGET 环境变量做平台判断，用 OUT_DIR 输出生成文件（如 bindgen 生成的 bindings.rs）。
11. CI 缓存：使用 Swatinem/rust-cache@v2（带 cache-on-failure: true、shared-key），或手动用 actions/cache@v3 缓存 ~/.cargo/registry/index/、~/.cargo/registry/cache/、~/.cargo/git/db/、target/，key 用 runner.os 加 Cargo.lock 的 hash。
12. 本地预热缓存：cargo fetch 下载全部依赖但不构建，cargo build --tests 构建包括测试在内的所有目标。
13. 发布构建通常关闭增量编译：在 [profile.release] 中设置 incremental = false（默认值，保持 false）。
14. 使用 cargo nextest 作为更快的测试运行器：cargo install cargo-nextest 安装，cargo nextest run 运行，cargo nextest list 列出测试，cargo nextest run --profile ci 用于 CI（JUnit 输出）。
15. 在 nextest.toml 中配置 profile：如 [profile.ci] 设置 fail-fast = false、test-threads = "num-cpus"、retries = { backoff = "exponential", count = 2, delay = "1s" }。
16. 依赖审计：cargo install cargo-audit 后运行 cargo audit 检查安全公告；cargo install cargo-deny 后运行 cargo deny check 检查许可证、重复版本与公告；cargo install cargo-machete 后运行 cargo machete 检查未使用依赖。
17. 在 deny.toml 中配置 [licenses] allow/deny 列表、[bans] multiple-versions = "warn" 与 deny 特定 crate、[advisories] ignore 列表。
18. 更新依赖：cargo update 更新到兼容版本，cargo update -p serde 更新单个包，cargo upgrade（cargo-edit）更新到最新版本。
19. 常用命令：cargo build --bin myapp 只构建指定二进制，cargo build --example myexample 只构建示例，cargo run -- --flag arg1 arg2 传参运行，cargo install cargo-expand 后 cargo expand module::path 展开宏，cargo tree 查看依赖树、--duplicates 查看多版本 crate、-i serde 查看谁依赖 serde，cargo metadata --format-version 1 | jq '.packages[].name' 查看元数据。