Cargo 基础命令体系
什么是 Cargo
Cargo 是 Rust 的官方包管理器和构建工具,随 Rustup 一起安装。它承担了 Rust 项目中几乎所有的日常工作:创建项目、编译代码、管理依赖、运行测试、生成文档、发布 crate 等等。可以说,写 Rust 代码离不开 Cargo,它相当于把 npm(包管理)、webpack(构建)、jest(测试)的功能合在了一个工具里。
创建项目
# 创建一个新的二进制项目(可执行程序)
# 会自动生成 Cargo.toml 和 src/main.rs
cargo new my-app
# 创建一个新的库项目
# 会自动生成 Cargo.toml 和 src/lib.rs
cargo new my-lib --lib
# 在当前已有的目录中初始化 Cargo 项目
# 不会创建新目录,直接在当前目录生成 Cargo.toml
cargo init
# 在当前目录初始化一个库项目
cargo init --libcargo new 和 cargo init 的区别:new 会创建新目录,init 在当前目录操作。如果你已经有了一个目录想把它变成 Rust 项目,用 init。
创建出来的项目结构:
my-app/
Cargo.toml # 项目清单文件(依赖、元数据等)
src/
main.rs # 程序入口(二进制项目)
# 或者
lib.rs # 库入口(库项目)编译与运行
# 编译项目(开发模式,不做优化,编译快)
# 编译产物在 target/debug/ 目录下
cargo build
# 编译并运行项目(最常用的命令)
# 等同于先 cargo build 再运行编译出来的可执行文件
cargo run
# 发布模式编译(开启优化,编译慢但运行快)
# 编译产物在 target/release/ 目录下
cargo build --release
# 发布模式运行
cargo run --release
# 只做语法和类型检查,不生成可执行文件(比 build 快很多)
# 开发过程中用来快速检查代码是否有编译错误
cargo checkcargo check 是开发过程中用得最多的命令之一。它只做编译检查不生成二进制文件,速度比 cargo build 快不少,特别是在大项目中。写代码时频繁运行 cargo check 能帮你尽早发现类型错误和借用问题。
依赖管理
# 添加一个依赖(会自动修改 Cargo.toml 并下载)
cargo add serde
# 添加依赖并启用特定 feature
cargo add serde --features derive
# 添加依赖并指定版本
cargo add tokio@1.35 --features full
# 添加开发依赖(只在测试和开发时使用)
cargo add mockall --dev
# 添加构建依赖(在 build.rs 中使用)
cargo add cc --build
# 移除一个依赖
cargo remove serde
# 更新依赖到 Cargo.toml 允许范围内的最新版本
# 这会修改 Cargo.lock 文件
cargo update
# 只更新特定的 crate
cargo update -p serde
# 查看依赖树(需要项目能编译通过)
cargo tree
# 查看哪些依赖有新版本可用(需要先安装 cargo-outdated)
# cargo install cargo-outdated
# cargo outdated测试
# 运行项目中所有的测试(单元测试 + 集成测试 + 文档测试)
cargo test
# 运行名字包含 "parse" 的测试
cargo test parse
# 运行特定模块的测试
cargo test tests::test_addition
# 运行测试时显示 println! 的输出(默认会被隐藏)
cargo test -- --nocapture
# 只运行被标记为 #[ignore] 的测试
cargo test -- --ignored
# 运行文档测试
cargo test --doc
# 以单线程运行测试(避免并发问题)
cargo test -- --test-threads=1代码质量工具
# 运行 Clippy 代码检查(Rust 官方的 lint 工具)
# 会给出代码风格建议和潜在 bug 警告
cargo clippy
# Clippy 检查并把警告视为错误(CI 中常用)
cargo clippy -- -D warnings
# 格式化代码(按照 Rust 官方风格)
cargo fmt
# 只检查格式是否正确,不做修改(CI 中常用)
cargo fmt -- --check文档生成
# 生成项目的文档并在浏览器中打开
cargo doc --open
# 生成文档但不包含依赖的文档(编译更快)
cargo doc --no-deps
# 生成文档并在浏览器中打开,不包含依赖
cargo doc --no-deps --open其他常用命令
# 清理编译产物(删除 target 目录)
# 当编译出现奇怪问题时,先 clean 再 build 通常能解决
cargo clean
# 安装一个 Rust 编写的命令行工具到 ~/.cargo/bin
cargo install ripgrep
# 查看当前安装的所有全局工具
cargo install --list
# 在 crates.io 上搜索 crate
cargo search json
# 查看项目的编译选项和特性
cargo metadata命令速查表
| 命令 | 功能 | 使用频率 |
|---|---|---|
cargo new <name> | 创建新项目 | 项目初始时 |
cargo build | 编译项目 | 经常 |
cargo run | 编译并运行 | 非常频繁 |
cargo check | 快速语法检查 | 非常频繁 |
cargo test | 运行测试 | 经常 |
cargo clippy | 代码检查 | 经常 |
cargo fmt | 格式化代码 | 经常 |
cargo add <crate> | 添加依赖 | 需要时 |
cargo update | 更新依赖 | 偶尔 |
cargo doc --open | 生成并查看文档 | 偶尔 |
cargo clean | 清理编译产物 | 偶尔 |
cargo build --release | 发布模式编译 | 发布时 |
基本示例
从创建项目到运行测试的完整流程:
# 创建项目
cargo new calculator
cd calculator编辑 src/main.rs:
// src/main.rs
// 加法函数
fn add(a: i32, b: i32) -> i32 {
a + b
}
// 减法函数
fn subtract(a: i32, b: i32) -> i32 {
a - b
}
fn main() {
let x = 10;
let y = 3;
println!("{} + {} = {}", x, y, add(x, y));
println!("{} - {} = {}", x, y, subtract(x, y));
}
// 测试模块,只在运行 cargo test 时编译
#[cfg(test)]
mod tests {
// 导入父模块的所有函数
use super::*;
#[test]
fn test_add() {
// assert_eq! 宏检查两个值是否相等
assert_eq!(add(2, 3), 5);
assert_eq!(add(-1, 1), 0);
assert_eq!(add(0, 0), 0);
}
#[test]
fn test_subtract() {
assert_eq!(subtract(5, 3), 2);
assert_eq!(subtract(1, 1), 0);
assert_eq!(subtract(0, 5), -5);
}
}# 快速检查有没有编译错误
cargo check
# 编译并运行
cargo run
# 运行测试
cargo test
# 检查代码风格
cargo clippy
# 格式化代码
cargo fmt常见问题
问题一:cargo build 和 cargo check 应该用哪个?
开发过程中建议用 cargo check,因为它只做类型检查不生成二进制文件,速度更快。当你确实需要运行程序或需要生成可执行文件时,再用 cargo build 或 cargo run。
问题二:cargo build 和 cargo build --release 有什么区别?
| 对比项 | cargo build | cargo build --release |
|---|---|---|
| 优化级别 | 不优化(opt-level = 0) | 最高优化(opt-level = 3) |
| 编译速度 | 快 | 慢(可能慢好几倍) |
| 运行速度 | 慢 | 快(通常比 debug 快 10-100 倍) |
| 调试信息 | 包含 | 默认不包含 |
| 产物位置 | target/debug/ | target/release/ |
| 适用场景 | 日常开发和调试 | 性能测试和正式发布 |
问题三:target 目录太大了怎么办?
target 目录存放所有编译产物和中间文件,一个项目的 target 目录可能达到几 GB。可以用 cargo clean 清理。注意 target 目录应该加到 .gitignore 里,不要提交到版本控制。
问题四:cargo add 命令报错说不识别怎么办?
cargo add 从 Rust 1.62 开始成为内置命令。如果你的 Rust 版本更老,需要先更新:rustup update stable。
适用场景
- 日常开发循环:
cargo check-> 写代码 ->cargo check->cargo run测试效果 - 提交代码前:
cargo fmt+cargo clippy+cargo test确保代码质量 - CI/CD 流水线:
cargo fmt -- --check+cargo clippy -- -D warnings+cargo test+cargo build --release - 添加依赖:
cargo add比手动编辑Cargo.toml更方便且不容易写错版本号格式 - 排查依赖问题:
cargo tree查看依赖树,找到冲突或重复的 crate
注意事项
cargo run默认运行src/main.rs中的main函数;如果项目只有src/lib.rs没有main.rs,cargo run会报错cargo test默认会并发运行测试,如果测试之间有共享状态(比如操作同一个文件),需要加-- --test-threads=1串行执行cargo clean会删除所有编译缓存,下次编译需要从头来,在大项目中可能需要很长时间- Cargo 命令都要在项目根目录(包含
Cargo.toml的目录)下运行,在其他目录运行会报错 - 如果编译报错信息看不懂,可以加上
RUST_BACKTRACE=1环境变量来获取更详细的错误堆栈 cargo install安装的是全局命令行工具,和项目依赖(cargo add)是两回事
总结
Cargo 是 Rust 开发的核心工具,覆盖了从项目创建到发布的完整流程。日常开发中最常用的命令是 cargo check(快速检查)、cargo run(编译运行)、cargo test(运行测试)。代码质量方面,cargo clippy 做代码审查,cargo fmt 统一代码风格。依赖管理方面,cargo add 添加依赖,cargo update 更新依赖。掌握这些基础命令后,你就能顺畅地进行 Rust 项目的开发工作了。随着项目复杂度增长,你还会接触到 workspace、自定义 profile、条件编译等进阶功能,但日常用到的命令就是上面这些。