Rust 工具链：环境准备与日常开发

这是 Rust 系统学习的第一步。完成本页后，应能创建项目、运行测试，并知道日常检查失败时从哪里排查。

安装与确认工具链

rustup 管理工具链和组件，rustc 编译 Rust 源码，cargo 管理项目、依赖和构建。安装前先看项目是否提供 rust-toolchain.toml 或 rust-toolchain；已有项目应优先使用其规定的版本。

新环境按官方安装说明安装。Windows 的 MSVC 工具链还需要相应的 C++ 构建工具；Linux、macOS 也需要平台要求的链接器。安装结束后重新打开终端检查：

rustup show
rustc --version
cargo --version

如果找不到命令，先检查安装是否完成、终端是否继承了新的 PATH。如果编译时找不到 linker，应检查系统构建工具，而不是重复下载 Rust。

对于没有版本约束的个人练习，可安装稳定工具链及常用组件：

rustup toolchain install stable
rustup component add rustfmt clippy --toolchain stable

安装不等于切换：回到练习目录运行 rustup show，确认当前选中的工具链。若没有项目版本约束但当前选中的是其他工具链，可在该练习目录运行 rustup override set stable；已有项目仍按它的版本配置执行。也可以用 cargo +stable run 只为单次命令选择工具链。参见工具链选择与覆盖规则。

项目的 edition 是 Cargo.toml 中的语言兼容性选项，不等于编译器版本；不同 edition 的 crate 可以协作。使用新 edition 前要检查其最低编译器版本。参见edition 指南。

创建并运行第一个项目

cargo new hello_rust
cd hello_rust
cargo run
cargo test

src/main.rs 是默认二进制入口，Cargo.toml 描述 package 与依赖。cargo run 会在需要时构建，然后运行程序。创建库项目使用 cargo new my_library --lib。

新建的二进制示例尚未定义测试，cargo test 显示零个测试也属正常；看到它成功，只能说明当前测试构建和测试运行完成，不能说明 main 的输出已被断言验证。接着阅读基础主线的断言与测试说明。

先让生成的示例工作，再开始替换为基础语法示例。这样可以区分环境问题和代码问题。参见Hello, Cargo!。

每次修改后的检查顺序

命令	用途	能证明什么
cargo fmt --check	检查格式	格式符合 rustfmt；不会自动改写文件
cargo check	快速检查当前默认目标	检查代码能否通过相应编译阶段，不生成最终可执行文件
cargo clippy --all-targets	检查库、二进制、测试等目标	提供额外 lint 建议，不替代测试
cargo test	编译并执行测试	验证被测试覆盖的行为
cargo build --release	构建发布配置	完成当前目标的优化构建，不代表所有行为已测试

格式不符时运行 cargo fmt 并检查差异。工作区项目通常还要选择 --workspace；features、目标平台和示例是否需要纳入检查，服从项目已有 CI 约定。不要为了让一条命令“覆盖更多”盲目启用互相不兼容的所有 features。

cargo check与cargo test有不同目标和构建行为；快速检查通过以后仍应运行项目测试。Clippy 使用说明解释了目标选择和 lint 配置。

理解依赖与锁文件

Cargo.toml 的版本要求说明允许哪些依赖版本；Cargo.lock 记录这次解析选择的具体版本。遵循项目约定提交和更新锁文件，避免一次无关修改夹带整批依赖变化。

cargo tree
cargo update -p dependency_name
cargo build --locked

dependency_name 需要换成真实依赖名称。cargo tree 查看实际依赖关系，cargo update -p 在清单约束内更新指定 package；--locked 要求锁文件保持不变，若需要变动则失败。它不表示离线运行，也不保证本地已有全部依赖。参见锁文件和cargo update。

下载确实受限时，应先确认是 Rust 工具链分发还是 Cargo registry 获取失败，再按组织要求配置；不要混淆 rustup 的下载地址和 Cargo 的 registry。Cargo 的项目与用户级配置位置见配置参考。

文档、编辑器与诊断

cargo doc --open
rustc --explain E0382

第一条为项目与依赖生成 API 文档并打开；第二条解释一个具体错误码，需替换成实际诊断中的代码。遇到编译错误先读第一条与自身代码相关的诊断，确认文件位置、期望类型和实际类型，再看编译器建议；不要连续套用建议而忽略所有权设计。

编辑器使用 rust-analyzer 提供补全、跳转和诊断。调试则取决于平台与所装调试器，可使用 GDB / LLDB 或对应的编辑器集成；Clippy 日常通过 cargo clippy 运行。

什么时候再看 nightly 和 Miri

学习本文与基础主线不需要 nightly。Miri 可检查执行路径上的若干未定义行为，适合深入研究 unsafe 等场景；它不能证明整个程序没有问题。Miri 通常通过 nightly 工具链安装和运行，应按 Miri 项目说明选择组件与命令，不能假定 cargo miri 已经随 stable 可用。

旧 gitbook 系列包含历史基准测试、编译器插件与 feature gate 写法，查用前需核对对应版本。正式发布 crate 是单独的发布流程；日常学习与本地验证无需运行 cargo publish。