Rust 工具与环境配置

刚开始学 Rust 时，一下子会冒出很多新名字：rustup、rustc、cargo、clippy、rustfmt、rust-analyzer。感觉好像得先装上十个工具，才能写下第一行代码。好消息是：一个安装程序就能把它们几乎全部装好，而且每个工具都只负责一件明确的事。

把它想象成一间厨房。rustup 是给你送厨具、帮你换新的商店；cargo 是统筹一切的主厨；clippy 是站在你身后、随时提点你的热心老师；rustfmt 负责让台面保持整洁。这一页会讲清楚每个工具的用途、各个操作系统需要准备什么，以及 Rust 开发者每天是怎么用这些工具的。

如果你还没装好 Rust，分步安装说明和第一个项目都在快速开始里。cargo 的基础用法（cargo new、cargo add、Cargo.toml）在 Cargo 与 crate 里。这一页是在这两页的基础上继续讲。

全局概览

整个工具箱，一张表就能看完：

工具	用途	随 rustup 一起安装？
`rustup`	安装 Rust、更新 Rust，并在不同版本之间切换	它本身就是安装程序
`rustc`	编译器：把 `.rs` 文件变成可以运行的程序	是
`cargo`	构建、运行、测试、添加 crate。几乎所有事都靠它	是
`rustup doc`	在浏览器里离线打开标准库文档和 Rust 程序设计语言（the Book）	是（default 配置）
`clippy`	代码检查工具（linter）：指出 bug，以及更简单的写法	是（default 配置）
`rustfmt`	代码格式化工具：把代码改写成标准风格	是（default 配置）
`rust-analyzer`	编辑器的“大脑”：自动补全、实时报错、类型提示、跳转到定义	默认不装。VS Code 扩展会自带一份
调试器	让程序停在某一行，查看变量的值	不包含。需要自己安装 LLDB 或 GDB（或者装一个自带调试器的编辑器扩展）

配置（profile）是 rustup 一次安装的一组组件。正常安装使用 default 配置，除了编译器和 cargo，还会装上文档、clippy 和 rustfmt。如果有人用 minimal 配置帮你装的 Rust，运行 cargo clippy 时会提示没有安装。一条命令就能解决：rustup component add clippy rustfmt。

试着运行一次 rustup doc --std。它会直接从你的硬盘打开完整的标准库文档，所以在飞机上或网速很慢时也能用。想看自己项目以及它用到的所有 crate 的文档，就运行 cargo doc --open（详见文档）。

安装之前：各个系统需要什么

Rust 负责编译代码，但到最后一步需要一个链接器（linker）：它把编译好的各个部分拼成一个可以运行的文件。Rust 用的是系统 C 工具链自带的链接器，所以每个操作系统都要多做一小步准备。

操作系统	需要安装	怎么装
Windows（推荐）	Visual Studio 的 C++ 工具：MSVC 链接器和 Windows SDK	在 Visual Studio 安装程序里勾选“使用 C++ 的桌面开发”（Desktop development with C++）工作负载
Windows（备选）	GNU 工具链（MinGW）	`rustup toolchain install stable-gnu`
Windows（另一种选择）	WSL，在 Windows 里运行的真正 Linux	`wsl --install`，然后按 Linux 的步骤来
macOS	Apple 的命令行工具（包含 C 编译器和链接器）	`xcode-select --install`
Debian / Ubuntu	C 编译器和链接器	`sudo apt install build-essential`
Fedora	C 编译器和链接器	`sudo dnf install gcc`

几点实话实说：

Windows 和 Visual Studio：这个不用你自己去找。如果缺少 Visual Studio，rustup-init.exe 会主动帮你安装。它装的是 Visual Studio Community，个人、学生和开源项目可以免费使用，但并不是所有公司都能免费用。如果在公司电脑上安装，先问问公司用的是哪个版本。勾选“使用 C++ 的桌面开发”工作负载，Rust 需要的东西就都齐了。
Windows 和 GNU：MSVC 工具链是默认选项，和其他 Windows 软件配合得最好。GNU 工具链编译简单程序时不需要 Visual Studio，但很多包含 C 代码的 crate 要等你装好 MSYS2 和 MinGW 才能编译成功。大多数人还是用 MSVC 就好。
WSL：如果你想在 Windows 上拥有一个 Linux 环境（比如你的服务器跑的是 Linux），WSL 是很好的选择。在 WSL 里面要用普通的 Linux 命令安装 Rust，它和 Windows 上的安装是相互独立的。
Linux 上的额外依赖：有些常用 crate 需要调用系统库。如果编译时报错，提到 pkg-config 或 OpenSSL，在 Ubuntu 上再装一下 pkg-config 和 libssl-dev。

准备好之后，按照快速开始里的步骤安装 Rust。

rustup 的日常用法

装好 Rust 之后，平时就靠 rustup 来维护它。Rust 每六周发布一个新的稳定版，所以经常更新是很正常的习惯：

rustup update     # 更新所有已安装的工具链（以及 rustup 自己）
rustup show       # 查看装了什么，以及当前目录正在使用哪个工具链

rustup show 的输出大致是这样（有删减）：

Default host: x86_64-unknown-linux-gnu

installed toolchains
--------------------
stable-x86_64-unknown-linux-gnu (active, default)

active toolchain
----------------
name: stable-x86_64-unknown-linux-gnu
active because: it's the default toolchain

stable、beta 和 nightly

工具链（toolchain）是一整套 rustc、cargo 以及配套工具。Rust 有三个发布渠道：

渠道	是什么	什么时候用
stable	正式版，每六周发布一次	几乎任何时候。你要的就是它
beta	正在测试中的下一个稳定版	想在下次发布前检查一下自己的项目
nightly	每晚构建，包含实验性特性	某个工具或 crate 要求使用，或者你想试试新特性

多个工具链可以同时安装、互不干扰：

rustup toolchain install nightly   # 在 stable 旁边再装一个 nightly
cargo +nightly build               # 只有这一条命令使用 nightly
rustup default stable              # 设置全局默认使用的工具链

为单个项目固定工具链

有时某个项目需要特定的 Rust 版本。在项目文件夹里放一个名为 rust-toolchain.toml 的文件，只要你在这个文件夹里工作，rustup 就会自动切换：

[toolchain]
channel = "1.97.0"
components = ["clippy", "rustfmt"]
targets = ["wasm32-unknown-unknown"]

把这个文件提交到 git。这样团队里的每个人（还有你的 CI）用的都是完全相同的编译器；如果谁的电脑上没有，rustup 会自动帮他装上。大多数小项目根本不需要这个文件，直接用最新的 stable 就行。

组件和目标平台

组件（component）是工具链的附加部分。目标平台（target）让你可以为另一种机器编译程序：

rustup component add clippy rustfmt rust-src   # rust-src：标准库源码，rust-analyzer 会用到
rustup component list --installed              # 查看已经装了哪些
rustup target add wasm32-unknown-unknown       # 把 Rust 编译成在浏览器里运行的代码

做 WebAssembly 开发需要的就是 wasm32-unknown-unknown 这个目标平台。

编辑器和 IDE

任何文本编辑器都能写 Rust，但一个带 rust-analyzer（或类似引擎）的编辑器会让体验完全不同。你一边打字就能看到错误，变量旁边会显示它的类型，还能一键跳到任何函数的定义。对新手来说，这种即时反馈就像身边坐着一位耐心的老师。

编辑器	价格	Rust 支持	适合谁
VS Code + rust-analyzer	免费	官方 rust-analyzer 扩展（英文）	大多数人。它是最流行的选择，大部分教程也默认你用它
RustRover（JetBrains）	非商业用途免费（学习、个人项目、无报酬的开源项目）。商业用途需要付费订阅	内置，使用 JetBrains 自己的 Rust 引擎，还自带调试器	喜欢功能齐全、开箱即用的 IDE 的人
Zed	免费，开源	内置（使用 rust-analyzer，调试用 CodeLLDB）	想要一个非常快的现代编辑器的人
Neovim / Helix	免费，开源	通过 rust-analyzer。Helix 几乎开箱即用；Neovim 需要一点配置	喜欢在终端里工作的人
Visual Studio	有付费版，也有免费的 Community 版	没有官方 Rust 支持	不太适合写 Rust。你只需要它的 C++ 生成工具来提供链接器

RustRover 的许可条款可能会变，在工作中使用之前，先到 RustRover 页面看看最新规定。

如果用 Neovim、Helix 或其他编辑器，用 rustup component add rust-analyzer 安装 rust-analyzer 程序本身。

调试

用 CodeLLDB 打断点

在 VS Code 里装好 rust-analyzer 和 CodeLLDB 后，你会在 fn main 和每个测试的上方看到小小的 Run | Debug 链接。点击行号左侧的空白处，设一个红色的断点，然后点 Debug。程序会停在断点处，你可以查看每个变量，并一行一行地执行代码。

如果想要一份可以反复使用的配置（比如要传命令行参数），就创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug task_queue",
      "cargo": {
        "args": ["build", "--bin=task_queue"]
      },
      "args": [],
      "cwd": "${workspaceFolder}"
    }
  ]
}

cargo 这部分告诉 CodeLLDB：先用 cargo 构建程序，再在调试器里启动它。把 task_queue 换成你的包名，程序参数写在 "args" 里。按 F5 开始调试。

用 `dbg!` 快速查看

并不是每次都需要完整的调试器。dbg! 宏会打印一个表达式、它的值，以及你写下它的文件和行号。它还会把值原样返回，所以几乎可以把它套在任何东西外面，而不改变代码的行为：

fn apply_discount(price: u32, percent: u32) -> u32 {
    price - price * percent / 100
}

fn main() {
    let prices = [120, 45, 80];

    let total: u32 = dbg!(prices.iter().sum());
    let final_price = dbg!(apply_discount(total, 10));

    println!("打九折后的总价：{final_price}");
}

输出：

打九折后的总价：221

▶ 动手试一试

dbg! 打印的内容去哪儿了？dbg! 输出到的是 stderr（标准错误流），而不是像 println! 那样输出到 stdout。这样调试信息就不会和真正的输出混在一起。在终端里，或者在 Playground 的 “Standard Error” 区域，你还会看到：

[src/main.rs:8:22] prices.iter().sum() = 245
[src/main.rs:9:23] apply_discount(total, 10) = 221

调试完记得把 dbg! 删掉。它们是给你自己看的，不是给用户看的。

每天都要做的代码质量检查

三条命令就能让代码保持健康。它们都很快，所以要经常运行。

`cargo check`：快速反馈

cargo check 只检查编译错误，不生成可运行的程序，所以比 cargo build 快得多。很多开发者每隔几分钟就运行一次。（编辑器里的 rust-analyzer 每次保存时都会替你做类似的检查。）

`cargo fmt`：再也不用争论代码风格

cargo fmt 会把项目里的每个文件都改写成标准的 Rust 风格。团队里谁都不用再纠结空格和换行了。它会把这样的代码：

struct Player{name:String,score:u32}
fn top(players:&[Player])->Option<&Player>{players.iter().max_by_key(|p|p.score)}

变成这样：

struct Player {
    name: String,
    score: u32,
}
fn top(players: &[Player]) -> Option<&Player> {
    players.iter().max_by_key(|p| p.score)
}

大多数编辑器都能在每次保存时自动运行它。在 VS Code 里，打开 “Format On Save”（保存时格式化）设置即可。

`cargo clippy`：友好的代码审查

Clippy 认识几百种写法：有的是错的，有的很慢，有的只是比必要的写法更难读。下面这个小程序运行起来完全没问题：

fn main() {
    let tasks: Vec<&str> = vec!["写文档", "修 bug"];

    if tasks.len() == 0 {
        println!("没有要做的事！");
    } else {
        println!("{} 个任务待处理", tasks.len());
    }
}

但 cargo clippy 给出了一条建议：

warning: length comparison to zero
 --> src/main.rs:4:8
  |
4 |     if tasks.len() == 0 {
  |        ^^^^^^^^^^^^^^^^ help: using `is_empty` is clearer and more explicit: `tasks.is_empty()`
  |
  = note: `#[warn(clippy::len_zero)]` on by default

意思是：和零比较长度，不如用 is_empty 更清楚。每条警告都有一个名字（这里是 len_zero），可以在 Clippy lint 列表（英文）里查到更详细的解释。修改后的版本是这样的：

fn main() {
    let tasks: Vec<&str> = vec!["写文档", "修 bug"];

    if tasks.is_empty() {
        println!("没有要做的事！");
    } else {
        println!("{} 个任务待处理", tasks.len());
    }
}

输出：

2 个任务待处理

▶ 动手试一试

cargo clippy --fix 可以自动帮你应用很多建议。Clippy 不一定总适合你的具体情况，但它说对的时候足够多，认真读每条警告是学习地道 Rust 写法的捷径。

实用的 cargo 扩展工具

任何人都可以给 cargo 添加新的子命令。用 cargo install 安装：它会下载源码、编译，然后把程序放到 ~/.cargo/bin（Windows 上是 %USERPROFILE%\.cargo\bin）。刚入门时一个都不需要，但值得知道它们的存在：

工具	用途	安装	运行
bacon（英文）	在旁边的终端里，每次保存时自动重新运行 check、clippy 或测试	`cargo install --locked bacon`	`bacon`、`bacon clippy`、`bacon test`
cargo-watch（英文）	保存时运行任意 cargo 命令。仍然能用，但已不再更新，作者推荐改用 bacon	`cargo install --locked cargo-watch`	`cargo watch -x check`
cargo-nextest（英文）	更快的测试运行器，输出也更清晰	`cargo install --locked cargo-nextest`	`cargo nextest run`
cargo-audit（英文）	对照已知的安全公告检查你的 `Cargo.lock`	`cargo install cargo-audit`	`cargo audit`
cargo-outdated（英文）	列出有新版本可用的依赖	`cargo install --locked cargo-outdated`	`cargo outdated`
cargo-edit（英文）	提供 `cargo upgrade`，用来升级 `Cargo.toml` 里的版本号（`cargo add` 已经内置了）	`cargo install cargo-edit`	`cargo upgrade`
cargo-expand（英文）	显示宏和 `#[derive]` 展开后的代码	`cargo install cargo-expand`	`cargo expand`
cargo-binstall（英文）	直接下载编译好的二进制文件，不用从源码编译，几秒钟就装好	`cargo install cargo-binstall`	`cargo binstall bacon`

cargo install 是从源码编译的，所以第一次安装大型工具可能要等几分钟，这很正常。以后想更新某个工具，再运行一次同样的安装命令就行。想看装过哪些，运行 cargo install --list。性能分析器、基准测试这类关注速度的工具，见性能。

什么都不用装：Rust Playground

Rust Playground 让你直接在浏览器里运行 Rust。本站每个“动手试一试”按钮打开的都是它。它非常适合快速做实验、求助时分享代码片段，或者在一台没法安装软件的电脑上学习。

它能做的事：

用 stable、beta 或 nightly 运行代码，可以选择 debug 或 release 构建。
使用 crates.io 上下载量最高的 100 个 crate（外加 Rust Cookbook 用到的 crate 及其依赖），比如 serde、rand、regex 和 tokio。
从 Tools 菜单运行 rustfmt 和 Clippy。
把代码以链接的形式分享出去。

它不能做的事：

只能有一个文件。没有 Cargo.toml，所以没法选择其他 crate 或版本。
不能访问网络。下载网页的代码会失败。
不能读写你自己的文件，也不能长时间运行。时间和内存都有限制。
不太适合交互式程序。程序运行时会出现一个小输入框，但除了简单测试，用起来很别扭。本站的示例都不读取输入，所以点一下就能运行。

等你觉得它不够用了，用 cargo new 建一个本地项目也就一分钟的事。

新电脑配置清单

在配置一台新电脑？按这个清单走一遍：

安装系统的前置依赖：Visual Studio C++ 工具（Windows）、xcode-select --install（macOS），或者 build-essential / gcc（Linux）。
从 rustup.rs 安装 Rust，然后打开一个新的终端。
检查一下：rustc --version 和 cargo --version。
确认日常工具都在：rustup component add clippy rustfmt。
安装一个支持 rust-analyzer 的编辑器。如果用 VS Code，装上 rust-analyzer 和 CodeLLDB 扩展。
在编辑器里打开“保存时格式化”。
用 cargo new hello 创建一个测试项目，在里面运行 cargo run、cargo clippy 和 cargo fmt。
设个提醒，每一两个月运行一次 rustup update。
可选：cargo install --locked bacon，写代码时能得到即时反馈。

练习

1. 检查你的工具箱

在自己的电脑上逐个运行下面这些命令，确认没有一个提示“未安装”：rustup show、cargo clippy --version、cargo fmt --version。然后打开离线标准库文档，找到 Vec 的页面。提示：rustup doc 可以接一个主题，比如类型的完整路径。

查看答案

rustup show
cargo clippy --version
cargo fmt --version
rustup doc std::vec::Vec

每条 --version 命令都会打印一个版本号。如果哪一条打印的是错误，就用 rustup component add clippy 或 rustup component add rustfmt 补装缺少的部分。最后一条命令会直接从你的硬盘在浏览器里打开 Vec 的页面。如果提示没有安装 rust-docs，先运行 rustup component add rust-docs。

2. 让 Clippy 教你

新建一个项目，把 Clippy 一节里任务程序的第一个版本粘贴到 src/main.rs。运行 cargo clippy，读一读警告，然后让 Clippy 自动帮你修好。提示：有一个参数可以自动应用建议。

查看答案

cargo new task_queue
cd task_queue
# 把程序粘贴到 src/main.rs，然后运行：
cargo clippy
cargo clippy --fix --allow-dirty
cargo clippy

第一次 cargo clippy 会显示 len_zero 警告。cargo clippy --fix 会把 tasks.len() == 0 改写成 tasks.is_empty()。--allow-dirty 参数允许它修改还没提交到 git 的文件。最后一次运行不会再打印任何警告。

总结

rustup 负责安装、更新 Rust 和切换工具链；cargo 负责构建、运行、测试和添加 crate；rustc 是底层的编译器。
每个系统都要先准备好链接器：Windows 上是 Visual Studio 的 C++ 工具，macOS 上是 xcode-select --install，Linux 上是 build-essential 或 gcc。
日常就用 stable。只有项目必须固定版本时才用 rust-toolchain.toml，临时用一下 nightly 就写 cargo +nightly。
用一个支持 rust-analyzer 的编辑器。VS Code 加 rust-analyzer 和 CodeLLDB 是最常见的组合。
经常运行 cargo check，每次提交前运行 cargo fmt 和 cargo clippy。快速查看用 dbg!，难缠的 bug 用调试器。
Playground 很适合做实验和分享代码，但只能有一个文件、不能联网，也只能用最流行的那些 crate。

小测验

1. 想在 stable 旁边再装一个 nightly 工具链，该用哪条命令？

2. 在 Windows 上编译失败，提示找不到链接器。最可能缺的是什么？

3. dbg! 把输出打印到哪里？

4. 下面哪件事是 Rust Playground 做不到的？

得分: 0 / 4

Rust 工具与环境配置

全局概览

安装之前：各个系统需要什么

rustup 的日常用法

stable、beta 和 nightly

为单个项目固定工具链

组件和目标平台

编辑器和 IDE

推荐的 VS Code 扩展

调试

用 CodeLLDB 打断点

用 `dbg!` 快速查看

每天都要做的代码质量检查

`cargo check`：快速反馈

`cargo fmt`：再也不用争论代码风格

`cargo clippy`：友好的代码审查

实用的 cargo 扩展工具

什么都不用装：Rust Playground

新电脑配置清单

练习

1. 检查你的工具箱

2. 让 Clippy 教你

总结

小测验

延伸阅读

Rust 工具与环境配置

全局概览

安装之前：各个系统需要什么

rustup 的日常用法

stable、beta 和 nightly

为单个项目固定工具链

组件和目标平台

编辑器和 IDE

推荐的 VS Code 扩展

调试

用 CodeLLDB 打断点

用 dbg! 快速查看

每天都要做的代码质量检查

cargo check：快速反馈

cargo fmt：再也不用争论代码风格

cargo clippy：友好的代码审查

实用的 cargo 扩展工具

什么都不用装：Rust Playground

新电脑配置清单

练习

1. 检查你的工具箱

2. 让 Clippy 教你

总结

小测验

延伸阅读

用 `dbg!` 快速查看

`cargo check`：快速反馈

`cargo fmt`：再也不用争论代码风格

`cargo clippy`：友好的代码审查