02-Cargo 指南 on 编程那些事儿

01-为什么需要 Cargo

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

为什么需要 Cargo

原文链接: https://doc.rust-lang.org/cargo/guide/why-cargo-exists.html

预备知识

在 Rust 中，你可能已经知道，库或可执行程序称为 crate。Crate 由 Rust 编译器 rustc 编译。刚开始学 Rust 时，大多数人最先接触到的源码是经典的 “hello world” 程序，并直接调用 rustc 来编译：

02-创建新包

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

创建新包

原文链接: https://doc.rust-lang.org/cargo/guide/creating-a-new-project.html

要用 Cargo 开始一个新包，使用 cargo new：

1

$ cargo new hello_world --bin

我们传入 --bin 是因为在创建二进制程序：若创建库，则应传入 --lib。默认情况下这也会初始化一个新的 git 仓库。若不希望如此，请传入 --vcs none。

03-在已有包上工作

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

在已有 Cargo 包上工作

原文链接: https://doc.rust-lang.org/cargo/guide/working-on-an-existing-project.html

如果你下载了一个使用 Cargo 的已有包，上手非常容易。

首先，从某处获取该包。本例中我们使用从 GitHub 仓库克隆的 regex：

04-依赖

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

依赖

原文链接: https://doc.rust-lang.org/cargo/guide/dependencies.html

crates.io 是 Rust 社区的中央包注册表（package registry），用作发现与下载包的位置。cargo 默认配置为使用它来查找所请求的包。

05-包布局

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

包布局

原文链接: https://doc.rust-lang.org/cargo/guide/project-layout.html

Cargo 对文件放置有约定，便于你快速上手一个新的 Cargo 包：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


.
├── Cargo.lock
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── main.rs
│   └── bin/
│ ├── named-executable.rs
│      ├── another-executable.rs
│      └── multi-file-executable/
│      ├── main.rs
│      └── some_module.rs
├── benches/
│   ├── large-input.rs
│   └── multi-file-bench/
│   ├── main.rs
│   └── bench_module.rs
├── examples/
│   ├── simple.rs
│   └── multi-file-example/
│   ├── main.rs
│   └── ex_module.rs
└── tests/
 ├── some-integration-tests.rs
 └── multi-file-test/
 ├── main.rs
 └── test_module.rs

Cargo.toml 与 Cargo.lock 存放在包的根目录（包根）。
源代码放在 src 目录中。
默认库文件是 src/lib.rs。
默认可执行文件是 src/main.rs。
- 其他可执行文件可放在 src/bin/ 中。
基准测试放在 benches 目录中。
示例放在 examples 目录中。
集成测试放在 tests 目录中。

若二进制、示例、基准测试或集成测试由多个源文件组成，请在 src/bin、examples、benches 或 tests 目录的子目录中放置一个 main.rs，连同额外的模块（module）。可执行文件的名称即为该子目录名。

06-Cargo.toml 与 Cargo.lock

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

Cargo.toml 与 Cargo.lock

原文链接: https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html

Cargo.toml 与 Cargo.lock 服务于两个不同的目的。在详细讨论之前，先做一个摘要：

Cargo.toml 用于从较宽泛的意义上描述你的依赖，由你来编写。
Cargo.lock 包含关于依赖的确切信息。它由 Cargo 维护，不应手工编辑。

拿不准时，请把 Cargo.lock 提交到版本控制系统（例如 Git）。要更好地理解原因以及可能的替代方案，参见常见问题中的「为什么要把 Cargo.lock 纳入版本控制？」。我们建议将其与验证最新依赖配合使用。

07-测试

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

测试

原文链接: https://doc.rust-lang.org/cargo/guide/tests.html

Cargo 可以用 cargo test 命令运行你的测试。Cargo 会在两个地方查找要运行的测试：每个 src 文件中，以及 tests/ 中的任何测试。src 文件中的测试应为单元测试与文档测试。tests/ 中的测试应为集成风格的测试。因此，你需要在 tests 中的文件里导入你的 crate。

08-持续集成

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

持续集成

原文链接: https://doc.rust-lang.org/cargo/guide/continuous-integration.html

入门

基本的 CI 会构建并测试你的项目：

GitHub Actions

要在 GitHub Actions 上测试你的包，下面是一个示例 .github/workflows/ci.yml 文件：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


name: Cargo Build & Test

on:
 push:
 pull_request:

env: 
 CARGO_TERM_COLOR: always

jobs:
 build_and_test:
 name: Rust project - latest
 runs-on: ubuntu-latest
 strategy:
 matrix:
 toolchain:
 - stable
 - beta
 - nightly
 steps:
 - uses: actions/checkout@v6
 - run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }}
 - run: cargo build --verbose
 - run: cargo test --verbose
 

这会在全部三个发行通道上测试（注意任一工具链版本失败都会导致整个作业失败）。你也可以在 GitHub UI 中点击 "Actions" > "new workflow" 并选择 Rust，将默认配置添加到仓库。更多信息参见 GitHub Actions 文档。

09-发布到 crates.io

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

发布到 crates.io

原文链接: https://doc.rust-lang.org/cargo/reference/publishing.html

一旦你有了想与世界分享的库，就可以把它发布到 crates.io！发布 crate 是指将特定版本上传并托管在 crates.io 上。

发布 crate 时请谨慎，因为发布通常是永久性的。版本永远无法被覆盖，代码也无法删除。不过，可以发布的版本数量没有限制。

首次发布之前

首先，你需要一个 crates.io 账户来获取 API token。为此，访问首页并通过 GitHub 账户登录（目前必须）。你还需要在账户设置页面提供并验证邮箱地址。完成后创建 API token，务必复制它。一旦离开该页面，你将无法再次看到它。

10-Cargo 主目录

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

Cargo 主目录

原文链接: https://doc.rust-lang.org/cargo/guide/cargo-home.html

「Cargo 主目录」用作下载与源码缓存。构建 crate 时，Cargo 会把下载的构建依赖存储在 Cargo 主目录中。你可以通过设置 CARGO_HOME 环境变量来改变 Cargo 主目录的位置。若需要在 Rust crate 内获取该位置，home crate 提供了相应 API。默认情况下，Cargo 主目录位于 $HOME/.cargo/。

11-优化构建性能

Thu, 30 Jul 2026 14:49:00 +0800

译文 · 基于 The Cargo Book

优化构建性能

原文链接: https://doc.rust-lang.org/cargo/guide/build-performance.html

Cargo 配置选项与源码组织模式可以帮助提升构建性能，做法是优先考虑构建性能，而非在你的情境下可能不那么重要的其他方面。

与优化运行时性能一样，请务必针对你实际关心的工作流来衡量这些改动。我们提供的是一般性指南，而你的情况可能不同；其中一些方法实际上可能使你的用例的构建性能变差。