[!info] related notes

• Cargo
• Rust
• [[cargo-moc|Cargo MOC]]

Cargo 命令速查

核心概念

Cargo.toml          项目清单（元数据 + 依赖声明）
Cargo.lock          精确版本锁定（类似 package-lock.json）
target/             构建产物目录
crates.io           官方包注册中心

---

项目创建与初始化

命令	说明	常用示例
cargo new <name>	创建二进制项目（可执行程序）	cargo new my-app
cargo new --lib <name>	创建库项目（纯 Rust 库）	cargo new --lib my-lib
cargo new --vcs git <name>	创建项目并初始化 Git	cargo new --vcs git my-app
cargo new --edition <year> <name>	指定 Rust 版本	cargo new --edition 2024 my-app
cargo init	在当前目录初始化项目	cargo init（二进制）
cargo init --lib	在当前目录初始化库项目	cargo init --lib

---

构建与运行

命令	说明	常用示例
cargo build	调试构建（输出到 target/debug/）	cargo build
cargo build --release	发布构建（开启优化，输出到 target/release/）	cargo build --release
cargo run	构建并运行	cargo run
cargo run -- <args>	运行时传递参数	cargo run -- arg1 arg2
cargo run --release	以发布模式运行	cargo run --release
cargo run --bin <name>	运行指定二进制目标	cargo run --bin my-tool
cargo run --example <name>	运行示例代码	cargo run --example hello
cargo check	快速语法/类型检查（不生成二进制）	cargo check（开发时推荐，比 build 快很多）
cargo clean	清理 target 目录	cargo clean

---

测试与基准

命令	说明	常用示例
cargo test	运行所有测试	cargo test
cargo test <name>	运行名称匹配的测试	cargo test test_parse
cargo test -- --nocapture	显示 println! 输出	cargo test -- --nocapture
cargo test -- --test-threads=1	单线程运行测试	cargo test -- --test-threads=1
cargo test --lib	只运行库测试	cargo test --lib
cargo test --doc	只运行文档测试	cargo test --doc
cargo test --release	以发布模式运行测试	cargo test --release
cargo bench	运行基准测试	cargo bench
cargo nextest run	使用 nextest 运行测试（更快，并行更好）	需先 cargo install cargo-nextest

---

依赖管理

命令	说明	常用示例
cargo add <crate>	添加依赖	cargo add serde
cargo add <crate>@<version>	添加指定版本依赖	cargo add serde@1.0
cargo add <crate> --features <f>	添加带特性的依赖	cargo add tokio --features full
cargo add <crate> --dev	添加为开发依赖	cargo add mockall --dev
cargo add <crate> --build	添加为构建依赖	cargo add cc --build
cargo add <crate> --rename <alias>	添加并重命名	cargo add my-crate --rename mc
cargo remove <crate>	移除依赖	cargo remove serde
cargo update	更新所有依赖（更新 Cargo.lock）	cargo update
cargo update <crate>	更新指定依赖	cargo update serde
cargo update --dry-run	预览更新（不实际修改）	cargo update --dry-run
cargo tree	查看依赖树	cargo tree
cargo tree -d	查看重复依赖	cargo tree -d
cargo tree -i <crate>	查看谁依赖了指定包	cargo tree -i serde
cargo tree --depth <n>	限制依赖树深度	cargo tree --depth 2
cargo outdated	检查过时依赖	需先 cargo install cargo-outdated

---

文档

命令	说明	常用示例
cargo doc	生成文档	cargo doc
cargo doc --open	生成并在浏览器打开	cargo doc --open
cargo doc --document-private-items	包含私有项的文档	cargo doc --document-private-items

---

发布与安装

命令	说明	常用示例
cargo publish	发布到 crates.io	cargo publish
cargo publish --dry-run	预览发布内容	cargo publish --dry-run
cargo package	打包但不发布	cargo package
cargo package --list	查看打包包含的文件	cargo package --list
cargo install <crate>	从 crates.io 安装二进制 crate	cargo install ripgrep
cargo install --path .	从本地项目安装	cargo install --path .
cargo install --list	列出已安装的 crate	cargo install --list
cargo uninstall <crate>	卸载已安装的 crate	cargo uninstall ripgrep

---

工作区 (Workspace)

命令	说明	常用示例
cargo build -p <member>	构建指定工作区成员	cargo build -p core
cargo test -p <member>	测试指定工作区成员	cargo test -p cli
cargo test --workspace	测试所有工作区成员	cargo test --workspace
cargo build --workspace	构建所有工作区成员	cargo build --workspace

工作区配置示例（根目录 Cargo.toml）：

[workspace]
members = [
    "crates/core",
    "crates/cli",
    "crates/web",
]
resolver = "2"

---

特性 (Features) 管理

命令	说明	常用示例
cargo build --features <f>	启用指定特性	cargo build --features json
cargo build --no-default-features	禁用默认特性	cargo build --no-default-features
cargo build --features "f1,f2"	启用多个特性	cargo build --features "json,yaml"

特性配置示例（Cargo.toml）：

[features]
default = ["sqlite"]
sqlite = ["rusqlite"]
postgres = ["tokio-postgres"]
json = ["serde_json"]

[dependencies]
rusqlite = { version = "0.27", optional = true }
tokio-postgres = { version = "0.7", optional = true }
serde_json = { version = "1.0", optional = true }

---

配置速查

配置项	说明	推荐值
[package] name	包名（crates.io 唯一）	snake_case
[package] version	语义化版本	0.1.0
[package] edition	Rust 版本	2021 或 2024
[dependencies]	运行时依赖	serde = "1.0"
[dev-dependencies]	开发/测试依赖	mockall = "0.11"
[build-dependencies]	构建脚本依赖	cc = "1.0"
[profile.dev]	开发构建配置	opt-level = 1（加速编译）
[profile.release]	发布构建配置	lto = true（链接时优化）
[profile.release] strip	去除调试符号	true（减小二进制体积）

---

常用插件

插件	用途	安装命令
cargo-edit	扩展 add/rm/upgrade 命令	cargo install cargo-edit
cargo-watch	文件变化自动重建/测试	cargo install cargo-watch
cargo-watch 用法	监听变化并运行	cargo watch -x check -x test
cargo-watch 用法	监听变化并运行程序	cargo watch -x run
cargo-audit	检查依赖安全漏洞	cargo install cargo-audit && cargo audit
cargo-expand	展开宏查看生成代码	cargo install cargo-expand
cargo-bloat	分析二进制体积	cargo install cargo-bloat
cargo-nextest	更快的测试运行器	cargo install cargo-nextest
cargo-outdated	检查过时依赖	cargo install cargo-outdated
cargo-clippy	Rust linter（随 rustup 自带）	cargo clippy
cargo-fmt	代码格式化（随 rustup 自带）	cargo fmt

---

常见问题速查

问题	原因	解决方案
编译缓慢	默认优化级别高或依赖多	开发时用 cargo check 代替 cargo build
下载依赖慢	网络问题	配置国内镜像源（中科大/字节）
版本冲突	依赖版本不兼容	cargo tree -d 查看冲突，用 [patch] 覆盖
内存不足	并行编译占用太多	CARGO_BUILD_JOBS=2 cargo build
cargo build 报链接错误	系统缺少链接器或库	安装对应系统依赖（如 pkg-config、openssl-dev）
二进制体积过大	包含调试符号	profile.release 中设置 strip = true 和 lto = true
Cargo.lock 冲突	Git 合并时冲突	删除 Cargo.lock 重新 cargo build，或 cargo update