Cargo 基本命令 #

命令概览 #

Cargo 提供了丰富的命令来管理 Rust 项目的整个生命周期。本节将详细介绍最常用的基本命令。

命令分类 #

text

Cargo 命令
├── 项目管理
│   ├── new         创建新项目
│   ├── init        初始化项目
│   └── locate-project  定位项目根目录
├── 构建
│   ├── build       编译项目
│   ├── check       快速检查
│   ├── run         运行项目
│   └── clean       清理构建
├── 依赖管理
│   ├── add         添加依赖
│   ├── remove      移除依赖
│   ├── update      更新依赖
│   └── tree        查看依赖树
├── 测试
│   ├── test        运行测试
│   └── bench       性能测试
├── 文档
│   └── doc         生成文档
└── 发布
    ├── publish     发布包
    └── install     安装二进制

项目创建命令 #

cargo new #

创建新的 Rust 项目。

bash

# 创建二进制项目（可执行程序）
cargo new my_project

# 创建库项目
cargo new my_lib --lib

# 指定项目名称（使用 kebab-case）
cargo new my-awesome-project

# 在现有目录中创建（目录必须为空）
cargo new --vcs none my_project    # 不初始化 git
cargo new --vcs git my_project     # 初始化 git（默认）

创建后的项目结构：

text

my_project/
├── Cargo.toml          # 项目配置
├── .git/               # Git 仓库
├── .gitignore          # Git 忽略文件
└── src/
    └── main.rs         # 程序入口

Cargo.toml 内容：

toml

[package]
name = "my_project"
version = "0.1.0"
edition = "2021"

[dependencies]

src/main.rs 内容：

rust

fn main() {
    println!("Hello, world!");
}

cargo init #

在现有目录中初始化 Rust 项目。

bash

# 在当前目录初始化
cargo init

# 创建二进制项目
cargo init --bin

# 创建库项目
cargo init --lib

# 指定目录
cargo init my_existing_dir

cargo locate-project #

定位项目的根目录。

bash

# 输出 Cargo.toml 的路径
cargo locate-project

# 输出项目根目录
cargo locate-project --message-format plain

构建命令 #

cargo build #

编译项目。

bash

# 开发模式编译（快速，包含调试信息）
cargo build

# 发布模式编译（优化，无调试信息）
cargo build --release

# 编译特定二进制
cargo build --bin my_binary

# 编译库
cargo build --lib

# 编译所有目标
cargo build --all-targets

# 指定并行任务数
cargo build -j 4
cargo build --jobs 4

# 编译特定包（工作区）
cargo build -p package_name

# 编译时启用特性
cargo build --features "feature1,feature2"

# 编译所有特性
cargo build --all-features

# 禁用默认特性
cargo build --no-default-features

# 指定目标平台
cargo build --target x86_64-pc-windows-gnu

# 详细输出
cargo build -v
cargo build --verbose

# 静默模式
cargo build -q
cargo build --quiet

编译模式对比 #

模式	命令	优化级别	调试信息	编译速度	运行速度
开发	`cargo build`	0-1	完整	快	慢
发布	`cargo build --release`	3	无	慢	快

输出目录 #

text

target/
├── debug/              # 开发模式输出
│   ├── my_project      # 可执行文件
│   ├── deps/           # 依赖编译结果
│   ├── examples/       # 示例程序
│   └── incremental/    # 增量编译缓存
└── release/            # 发布模式输出
    ├── my_project
    └── deps/

cargo check #

快速检查代码错误，不生成可执行文件。

bash

# 检查当前项目
cargo check

# 检查所有目标
cargo check --all-targets

# 检查特定包
cargo check -p package_name

# 检查时启用特性
cargo check --features "feature1"

# 发布模式检查
cargo check --release

# 详细输出
cargo check -v

💡 提示：cargo check 比 cargo build 快得多，适合开发过程中频繁使用。

cargo run #

编译并运行项目。

bash

# 运行项目
cargo run

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

# 传递参数给程序
cargo run -- arg1 arg2 arg3

# 运行特定二进制
cargo run --bin my_binary

# 运行示例程序
cargo run --example my_example

# 指定特性
cargo run --features "feature1"

参数传递示例 #

rust

// src/main.rs
fn main() {
    let args: Vec<String> = std::env::args().collect();
    println!("Arguments: {:?}", args);
}

bash

cargo run -- hello world
# 输出：Arguments: ["target/debug/my_project", "hello", "world"]

cargo clean #

清理构建输出。

bash

# 清理所有构建输出
cargo clean

# 只清理发布输出
cargo clean --release

# 清理特定包的输出
cargo clean -p package_name

# 清理特定文档
cargo clean --doc

依赖管理命令 #

cargo add #

添加依赖到 Cargo.toml。

bash

# 添加依赖
cargo add serde

# 添加特定版本
cargo add serde@1.0

# 添加开发依赖
cargo add --dev serde_json

# 添加构建依赖
cargo add --build cc

# 添加特定特性
cargo add serde --features derive

# 添加 Git 依赖
cargo add --git https://github.com/serde-rs/serde.git

# 添加本地路径依赖
cargo add --path ../my_lib

# 添加可选依赖
cargo add --optional some_lib

# 重命名依赖
cargo add serde --rename my_serde

添加后的 Cargo.toml：

toml

[dependencies]
serde = { version = "1.0", features = ["derive"] }

[dev-dependencies]
serde_json = "1.0"

[build-dependencies]
cc = "1.0"

cargo remove #

从 Cargo.toml 移除依赖。

bash

# 移除依赖
cargo remove serde

# 移除开发依赖
cargo remove --dev serde_json

# 移除构建依赖
cargo remove --build cc

cargo update #

更新依赖版本。

bash

# 更新所有依赖
cargo update

# 更新特定依赖
cargo update -p serde

# 更新到特定版本
cargo update -p serde@1.0.0

# 更新到最新版本
cargo update -p serde --precise 1.0.193

⚠️ 注意：cargo update 会更新 Cargo.lock 文件，确保团队使用相同的依赖版本。

cargo tree #

查看依赖树。

bash

# 查看依赖树
cargo tree

# 显示重复依赖
cargo tree --duplicates

# 显示特性
cargo tree --features

# 反向依赖（谁依赖了这个包）
cargo tree -i serde

# 指定格式
cargo tree --format "{p} {f}"

# 只显示直接依赖
cargo tree --depth 1

输出示例：

text

my_project v0.1.0 (/path/to/my_project)
├── serde v1.0.193
│   └── serde_derive v1.0.193 (proc-macro)
│       ├── proc-macro2 v1.0.78
│       │   └── unicode-ident v1.0.12
│       ├── quote v1.0.35
│       │   └── proc-macro2 v1.0.78 (*)
│       └── syn v2.0.48
│           ├── proc-macro2 v1.0.78 (*)
│           ├── quote v1.0.35 (*)
│           └── unicode-ident v1.0.12
└── serde_json v1.0.110
    ├── itoa v1.0.10
    ├── ryu v1.0.16
    └── serde v1.0.193 (*)

测试命令 #

cargo test #

运行测试。

bash

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_name

# 运行匹配模式的测试
cargo test test_prefix_

# 运行被忽略的测试
cargo test -- --ignored

# 运行所有测试（包括被忽略的）
cargo test -- --include-ignored

# 显示测试输出
cargo test -- --nocapture

# 并行运行测试
cargo test -- --test-threads=4

# 串行运行测试
cargo test -- --test-threads=1

# 运行特定测试文件
cargo test --test integration_test

# 运行文档测试
cargo test --doc

# 运行单元测试
cargo test --lib

# 发布模式测试
cargo test --release

cargo bench #

运行性能测试。

bash

# 运行所有性能测试
cargo bench

# 运行特定测试
cargo bench bench_name

# 保存基准结果
cargo bench -- --save-baseline main

# 与基准比较
cargo bench -- --baseline main

文档命令 #

cargo doc #

生成项目文档。

bash

# 生成文档
cargo doc

# 生成并打开文档
cargo doc --open

# 包含依赖文档
cargo doc --document-private-items

# 生成私有项文档
cargo doc --document-private-items

# 指定输出目录
cargo doc --target-dir ./docs

# 发布模式
cargo doc --release

生成的文档位于 target/doc/ 目录。

其他常用命令 #

cargo version #

查看版本信息。

bash

cargo --version
cargo -V

cargo help #

获取帮助信息。

bash

# 查看帮助
cargo help
cargo --help

# 查看特定命令帮助
cargo help build
cargo build --help

cargo metadata #

输出项目元数据（JSON 格式）。

bash

cargo metadata

# 格式化输出
cargo metadata --format-version 1

# 不依赖解析
cargo metadata --no-deps

cargo install #

安装二进制包。

bash

# 安装包
cargo install ripgrep

# 安装特定版本
cargo install ripgrep@13.0.0

# 安装特定二进制
cargo install --bin rg ripgrep

# 从 Git 安装
cargo install --git https://github.com/BurntSushi/ripgrep

# 安装到指定目录
cargo install --root /usr/local ripgrep

# 列出已安装的包
cargo install --list

# 强制重新安装
cargo install --force ripgrep

cargo uninstall #

卸载已安装的二进制包。

bash

cargo uninstall ripgrep

cargo search #

搜索 crates.io 上的包。

bash

# 搜索包
cargo search serde

# 限制结果数量
cargo search serde --limit 10

登录到 crates.io。

bash

cargo login
cargo login <token>

cargo owner #

管理包的所有者。

bash

# 添加所有者
cargo owner --add username

# 移除所有者
cargo owner --remove username

# 列出所有者
cargo owner --list

cargo yank #

从索引中移除特定版本。

bash

# yank 版本
cargo yank --vers 1.0.0

# 取消 yank
cargo yank --vers 1.0.0 --undo

命令选项速查 #

通用选项 #

选项	简写	描述
`--help`	`-h`	显示帮助信息
`--version`	`-V`	显示版本
`--verbose`	`-v`	详细输出
`--quiet`	`-q`	静默模式
`--color`		控制颜色输出
`--frozen`		要求 Cargo.lock 和缓存是最新的
`--locked`		要求 Cargo.lock 是最新的
`--offline`		离线模式

构建选项 #

选项	描述
`--release`	发布模式编译
`--target <triple>`	指定目标平台
`--features <features>`	启用特性
`--all-features`	启用所有特性
`--no-default-features`	禁用默认特性
`-j, --jobs <n>`	并行任务数

包选择选项 #

选项	描述
`-p, --package <spec>`	指定包
`--workspace`	所有工作区成员
`--all`	所有包（同 --workspace）
`--exclude <spec>`	排除包

命令别名 #

可以在 .cargo/config.toml 中定义命令别名：

toml

[alias]
b = "build"
c = "check"
r = "run"
t = "test"
br = "build --release"
rr = "run --release"

使用别名：

bash

cargo b      # 等同于 cargo build
cargo br     # 等同于 cargo build --release

下一步 #

掌握了基本命令后，继续学习 Cargo.toml 配置详解深入了解项目配置！

Cargo 基本命令 #

命令概览 #

命令分类 #

项目创建命令 #

cargo new #

cargo init #

cargo locate-project #

构建命令 #

cargo build #

编译模式对比 #

输出目录 #

cargo check #

cargo run #

参数传递示例 #

cargo clean #

依赖管理命令 #

cargo add #

cargo remove #

cargo update #

cargo tree #

测试命令 #

cargo test #

cargo bench #

文档命令 #

cargo doc #

其他常用命令 #

cargo version #

cargo help #

cargo metadata #

cargo install #

cargo uninstall #

cargo search #

cargo login #

cargo owner #

cargo yank #

命令选项速查 #

通用选项 #

构建选项 #

包选择选项 #

命令别名 #

下一步 #