Cargo 入门指南：Rust 的构建工具和包管理器

发布于 2026年06月24日 18:30 #DevOps #CLI

Cargo 是 Rust 官方构建工具和包管理器，集成测试、格式化、代码检查等全家桶功能
常用命令包括 cargo new、cargo build、cargo run、cargo test 和 cargo check
依赖在 Cargo.toml 中声明，cargo build 时自动下载编译，无需手动 install
Cargo.lock 文件精确锁定依赖版本，保证团队和 CI 环境构建一致性
项目结构约定 src/main.rs 或 lib.rs，examples、tests、benches 等目录自动识别

什么是 Cargo

Cargo 是 Rust 官方的构建工具和包管理器，安装 Rust 时就会自动带上。简单类比：Cargo 之于 Rust，就像 npm 之于 Node.js，pip 之于 Python，Maven 之于 Java。

Cargo 管所有事——不用像 Python 那样分别装 pytest、black、mypy，也不用像 Node.js 那样配置 eslint、prettier、jest。Rust 生态中，cargo test（测试）、cargo fmt（格式化）、cargo clippy（代码检查）都是内置或官方组件，一个 cargo 全包了。

Cargo 管哪些事

职责	说明
创建项目	`cargo new` / `cargo init` 生成标准项目骨架
编译代码	`cargo build` 调用 rustc 编译，管理增量编译
运行程序	`cargo run` 编译 + 运行，一步到位
下载依赖	在 `Cargo.toml` 里声明，`cargo build` 时自动从 crates.io 拉取
运行测试	`cargo test` 跑所有单元测试和集成测试
生成文档	`cargo doc --open` 自动生成 HTML 文档并在浏览器打开
发布 crate	`cargo publish` 把你的库发布到 crates.io

最常用的命令

# 创建新项目
cargo new my_project        # 生成目录 + Cargo.toml + src/main.rs
cargo init                  # 在当前目录初始化

# 编译（debug 模式，快但未优化）
cargo build
# 编译（release 模式，优化过，慢但跑得快）
cargo build --release

# 编译 + 运行（日常开发最常用）
cargo run
cargo run --example demo    # 运行 examples 下的文件

# 只检查能不能编译过，不生成可执行文件（比 build 快得多）
cargo check

# 运行测试
cargo test
cargo test --example test_demo    # 运行特定 example 里的测试

# 添加第三方库（会自动更新 Cargo.toml 并下载）
cargo add serde
cargo add tokio --features full   # 带 feature 参数

日常开发 90% 的情况就是 cargo run、cargo test、cargo check 三个命令来回用。有任何命令不懂，直接 cargo help <子命令> 就能看文档。

核心文件：`Cargo.toml`

这是项目根目录下的配置文件，相当于项目的“身份证”：

[package]
name = "rust_demo"        # 项目名
version = "0.1.0"         # 版本号
edition = "2021"          # Rust 版本（2021 是目前主流）

[dependencies]            # 第三方依赖写在这里
serde = "1.0"            # 序列化库
tokio = { version = "1", features = ["full"] }  # 异步运行时

Cargo 的依赖管理有个特别方便的地方：你在 Cargo.toml 里写上库名，下次 cargo build 或 cargo run 时自动下载编译，不像 pip install / npm install 需要你主动执行安装命令。

另外 Cargo 会自动生成 Cargo.lock 文件，精确锁定依赖版本，保证你和同事、CI 环境编译出来的结果一模一样。这个文件不要手动编辑，cargo 自己维护。

对比你熟悉的工具

操作	Cargo (Rust)	npm (Node.js)	pip (Python)	Maven/Gradle (Java)	Go (go mod)
创建新项目	`cargo new my-app`	`npm init`	手动创建目录	IDE 或手动	`mkdir && go mod init`
初始化已有目录	`cargo init`	`npm init`	—	—	`go mod init`
添加依赖	`cargo add serde` 或编辑 `Cargo.toml`	`npm install express`	`pip install requests`	编辑 `pom.xml`	`go get github.com/xxx`
安装所有依赖	自动（`cargo build` 时）	`npm install`	`pip install -r requirements.txt`	`mvn install`	`go mod download`
编译	`cargo build`	—（解释型，不需要）	—（解释型，不需要）	`mvn compile`	`go build`
编译 + 运行	`cargo run`	`node index.js`	`python main.py`	`mvn exec:java`	`go run main.go`
只检查不编译	`cargo check`（非常快！）	—	—	—	`go vet`
运行测试	`cargo test`	`npm test`	`pytest`	`mvn test`	`go test ./...`
Release 构建	`cargo build --release`	—	—	`mvn package`	`go build -ldflags="-s -w"`
代码格式化	`cargo fmt`	`prettier`	`black`	IDE 插件	`go fmt`
代码检查	`cargo clippy`	`eslint`	`ruff / pylint`	`checkstyle`	`golangci-lint`
生成文档	`cargo doc --open`	—	—	`mvn javadoc:javadoc`	`go doc`
发布	`cargo publish`	`npm publish`	`twine upload`	`mvn deploy`	—
配置文件	`Cargo.toml`	`package.json`	`pyproject.toml`	`pom.xml`	`go.mod`
锁文件	`Cargo.lock`	`package-lock.json`	—	—	`go.sum`
注册中心	crates.io	npmjs.com	pypi.org	Maven Central	pkg.go.dev

三个关键差异

1. Cargo 是“全家桶”，不用东拼西凑

Python 需要分别装 pytest、black、mypy，Node.js 需要 eslint、prettier、jest。Rust 一个 cargo 全包了——cargo test（测试）、cargo fmt（格式化）、cargo clippy（代码检查）都是内置或官方组件，不需要额外装工具。

2. 依赖不用手动 `install`

在 Cargo.toml 里写个库名，下次 cargo build 或 cargo run 时自动下载编译。不像 pip install / npm install 需要你主动执行安装命令。这个设计省了一步操作，也避免了“忘了 install 结果报错”的尴尬。

3. 编译型语言的额外好处

Rust 是编译型语言，所以比 Python/Node.js 多了个编译步骤。但 cargo check 只检查代码能不能过编译，不生成可执行文件，速度飞快——开发时改完代码跑一下 cargo check，几秒就知道有没有写错，比完整 cargo build 快得多，是很实用的开发工作流。

项目结构约定

Cargo 对项目目录结构有约定，遵循这些约定可以让工具自动识别：

my_project/
├── Cargo.toml          # 项目配置文件
├── Cargo.lock          # 依赖版本锁定（不要手动编辑）
├── src/
│   ├── main.rs         # 二进制入口（默认）
│   └── lib.rs          # 库入口
├── examples/           # 示例代码（cargo run --example xxx）
├── tests/              # 集成测试
├── benches/            # 性能基准测试
└── target/             # 编译输出（可以删，会自动重建）

总结

如果你从其他语言转来 Rust，Cargo 是第一个要熟悉的东西。好在它设计得很直觉——大部分命令看一眼就能猜出作用，而且 Rust 工具链的一致性远超 Python/Node.js 生态。日常开发记住 cargo run、cargo test、cargo check 三个命令就够用了。