Cargo 基础命令体系 ​

什么是 Cargo ​

Cargo 是 Rust 的官方包管理器和构建工具,随 Rustup 一起安装。它承担了 Rust 项目中几乎所有的日常工作:创建项目、编译代码、管理依赖、运行测试、生成文档、发布 crate 等等。可以说,写 Rust 代码离不开 Cargo,它相当于把 npm(包管理)、webpack(构建)、jest(测试)的功能合在了一个工具里。

创建项目 ​

powershell
# 创建一个新的二进制项目(可执行程序)
# 会自动生成 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 --lib

cargo new 和 cargo init 的区别:new 会创建新目录,init 在当前目录操作。如果你已经有了一个目录想把它变成 Rust 项目,用 init。

创建出来的项目结构:

my-app/
  Cargo.toml          # 项目清单文件(依赖、元数据等)
  src/
    main.rs            # 程序入口(二进制项目)
  # 或者
    lib.rs             # 库入口(库项目)

编译与运行 ​

powershell
# 编译项目(开发模式,不做优化,编译快)
# 编译产物在 target/debug/ 目录下
cargo build

# 编译并运行项目(最常用的命令)
# 等同于先 cargo build 再运行编译出来的可执行文件
cargo run

# 发布模式编译(开启优化,编译慢但运行快)
# 编译产物在 target/release/ 目录下
cargo build --release

# 发布模式运行
cargo run --release

# 只做语法和类型检查,不生成可执行文件(比 build 快很多)
# 开发过程中用来快速检查代码是否有编译错误
cargo check

cargo check 是开发过程中用得最多的命令之一。它只做编译检查不生成二进制文件,速度比 cargo build 快不少,特别是在大项目中。写代码时频繁运行 cargo check 能帮你尽早发现类型错误和借用问题。

依赖管理 ​

powershell
# 添加一个依赖(会自动修改 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

测试 ​

powershell
# 运行项目中所有的测试(单元测试 + 集成测试 + 文档测试)
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

代码质量工具 ​

powershell
# 运行 Clippy 代码检查(Rust 官方的 lint 工具)
# 会给出代码风格建议和潜在 bug 警告
cargo clippy

# Clippy 检查并把警告视为错误(CI 中常用)
cargo clippy -- -D warnings

# 格式化代码(按照 Rust 官方风格)
cargo fmt

# 只检查格式是否正确,不做修改(CI 中常用)
cargo fmt -- --check

文档生成 ​

powershell
# 生成项目的文档并在浏览器中打开
cargo doc --open

# 生成文档但不包含依赖的文档(编译更快)
cargo doc --no-deps

# 生成文档并在浏览器中打开,不包含依赖
cargo doc --no-deps --open

其他常用命令 ​

powershell
# 清理编译产物(删除 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发布模式编译发布时

基本示例 ​

从创建项目到运行测试的完整流程:

powershell
# 创建项目
cargo new calculator
cd calculator

编辑 src/main.rs:

rust
// 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);
    }
}
powershell
# 快速检查有没有编译错误
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 buildcargo 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、条件编译等进阶功能,但日常用到的命令就是上面这些。