12-Cargo使用指南

精要笔记 · 基于 Rust语言圣经「Cargo 使用指南」

Cargo 使用指南

Cargo = Rust 包管理 + 构建工具；crates.io 为社区注册中心。本章基于 Cargo Book 整理。

上手使用

Package（项目） ≠ Crate（包）。cargo new hello_world 默认 --bin 二进制项目。

1
2
3

hello_world/
├── Cargo.toml    # 清单 manifest
└── src/main.rs

基础指南

为何会有 Cargo

rustc 直接编译的问题：多文件、编译参数、依赖版本管理复杂。Cargo 四件事：

1. Cargo.toml + Cargo.lock 元数据
2. 拉取/构建依赖（crates.io 等）
3. 调用 rustc 并传正确参数
4. 约定目录结构，降低学习成本

下载并构建 Package

• cargo build：首次拉依赖并编译
• cargo update：更新 lock 中依赖（在允许范围内）
• 离线/缓存命中时跳过下载

添加依赖

Cargo.toml：

1
2

[dependencies]
serde = "1.0"

• cargo add 包名（新版 Cargo）自动写入
• 修改后 cargo build 自动解析

Package 目录结构

标准布局：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

.
├── Cargo.toml
├── Cargo.lock          # 应用项目通常提交
├── src/
│   ├── main.rs         # bin 默认入口
│   └── lib.rs          # lib 默认入口
├── tests/              # 集成测试
├── benches/            # 基准测试
├── examples/           # 示例
└── build.rs            # 构建脚本（可选）

• 二进制：src/bin/*.rs 或 [[bin]] 指定
• 库：src/lib.rs 或 [[lib]]

Cargo.toml vs Cargo.lock

是否提交 lock：

• 库 crate（被他人依赖）→ .gitignore lock
• 终端产品（CLI/应用）→ 提交 lock，保证可复现构建

原因：下游引入库时不应被库的 lock 约束；应用需要确定性环境。

无 lock 时 Cargo 解析最新兼容版本；有 lock 则锁定直到 cargo update。

测试和 CI

• cargo test / cargo check（只检查不产出二进制，更快）
• CI 常用：cargo test --all-features、缓存 ~/.cargo 与 target/
• 平台：GitHub Actions / Travis / GitLab CI

Cargo 缓存

Cargo Home（默认 ~/.cargo）：

• registry/：crate 源码缓存
• git/：git 依赖
• bin/：安装的 binary

CI 缓存 Cargo Home 可大幅加速。卡住 Blocking waiting for file lock → 并发构建争锁，稍等或杀残留进程。

Build 缓存

target/ 结构：

• target/debug/ 或 target/release/：产物
• target/<triple>/：交叉编译
• .fingerprint/、.d 文件：增量编译依赖追踪

共享缓存：多项目可配置同一 target 目录（workspace 天然共享）。

进阶指南

指定依赖项

版本语法（semver）：

其他来源：

1
2
3

dep = { git = "https://...", rev = "abc123" }
dep = { path = "../local-crate" }
dep = { version = "1.0", registry = "..." }

• [target.'cfg(windows)'.dependencies] 平台依赖
• [dev-dependencies] 仅测试/示例
• [build-dependencies] 仅 build.rs
• package = { ... } 重命名依赖

依赖覆盖

[patch] 临时替换依赖源（测 bugfix、本地 fork）：

1
2

[patch.crates-io]
serde = { git = "..." }

• 可 patch 间接依赖
• [replace] 已不推荐

Cargo.toml 清单详解

[package] 常用字段：

[badges]：maintenance 状态等。

Cargo Target

五类 target：lib / bin / example / test / bench

Cargo.toml 可显式配置：

1
2
3
4

[[bin]]
name = "my_tool"
path = "src/bin/tool.rs"
required-features = ["cli"]

• crate-type：lib、cdylib、staticlib 等
• proc-macro = true：过程宏 crate
• 自动发现：src/bin/*.rs、examples/、benches/、tests/

工作空间 Workspace

多 package 共享 Cargo.lock 与 target/。

两种：

1. 根 package：根 Cargo.toml 含 [package] + [workspace] members = [...]
2. 虚拟 manifest：仅 [workspace]，无根 package

常用命令：

1
2

cargo build -p crate_name     # 指定 member
cargo test --workspace        # 全 workspace

[workspace.metadata] 供工具读取。

条件编译 Features

1
2
3
4

[features]
default = ["std"]
webp = ["dep:webp-decoder"]
full = ["webp", "async"]

要点：

• default 默认启用；--no-default-features
• 可选依赖：optional = true + feature 启用
• 命令行：cargo build --features "a,b"
• feature 统一化：同名 feature 合并启用
• required-features：bin/example 按需启用
• Resolver V2：避免 feature 意外传播

发布配置 Profile

常用设置：

[profile.release.package.foo] opt-level = 3 可 per-crate 覆盖。

通过 config.toml 对 Cargo 进行配置

层级（后者覆盖前者）：

1. $CARGO_HOME/config.toml
2. 项目 .cargo/config.toml
3. 环境变量 CARGO_*

可配置：registry mirror、build target、[patch]、[alias]、[env] 等。

发布到 crates.io

流程：

1. crates.io 注册 + cargo login
2. 完善 Cargo.toml 元数据、README、license
3. cargo publish --dry-run / cargo package 检查
4. cargo publish
5. 新版本 bump version 再 publish

管理：cargo yank 撤版本（不删）；cargo owner 管理协作者。

构建脚本 build.rs

• 项目根 build.rs，编译为独立程序，先于主 crate 运行
• 输出：cargo:rustc-link-lib=...、cargo:rerun-if-changed=... 等
• 用途：代码生成、编译 C 库、条件编译
• [build-dependencies] 引入 build 专用 crate
• links key 防止多 crate 重复链接同一本地库

速查

1
2
3
4
5

cargo check / build / run / test
cargo add 包名
cargo update -p 包名
cargo tree                    # 依赖树
cargo publish --dry-run