Rust学习教程1：搭建 Rust 环境

Rust学习教程1：搭建 Rust 环境的详细入门指南

从零开始，手把手教你用 VS Code / Cursor 搭建完整的 Rust 开发环境，包含安装、配置、调试与常见问题解决。

📑 目录

• [一、🚀 为什么选择 VS Code + Rust？](#一、🚀 为什么选择 VS Code + Rust？)
• [二、🛠️ 环境准备](#二、🛠️ 环境准备)
• [三、⬇️ 安装 Rust 工具链](#三、⬇️ 安装 Rust 工具链)
• [四、📦 Cargo 包管理器入门](#四、📦 Cargo 包管理器入门)
• [五、🔌 安装 rust-analyzer 扩展](#五、🔌 安装 rust-analyzer 扩展)
• [六、🎯 创建你的第一个 Rust 项目](#六、🎯 创建你的第一个 Rust 项目)
• [七、⚡ rust-analyzer 核心功能](#七、⚡ rust-analyzer 核心功能)
• [八、🐛 配置调试环境](#八、🐛 配置调试环境)
• [九、❓ 常见问题与解决方案](#九、❓ 常见问题与解决方案)
• [十、📚 学习资源](#十、📚 学习资源)
• [十一、✅ 总结](#十一、✅ 总结)

---

一、🚀 为什么选择 VS Code + Rust？

Rust 作为一门系统级编程语言，凭借其内存安全、零成本抽象和高性能等特性，近年来深受开发者喜爱。而在编辑器选择上，VS Code + rust-analyzer 是目前官方推荐的最佳组合------rust-analyzer 对 VS Code 的支持最为完善，能提供出色的代码补全、类型提示、跳转定义和重构能力。

本指南将覆盖从环境安装到进阶配置的完整流程，适合 Rust 初学者和希望优化开发体验的开发者。

图 1：使用 VS Code 打开 Rust 项目的界面示意

---

二、🛠️ 环境准备

2.1 📥 安装 Visual Studio Code

1. 访问 VS Code 官网 下载安装包
2. 根据你的操作系统选择对应版本（Windows / macOS / Linux）
3. 安装完成后，确保 VS Code 版本较新（rust-analyzer 仅支持最近两个主要版本）

2.2 💻 系统要求

操作系统	额外要求
Windows	需要安装 C++ 构建工具（用于链接器 link.exe），rustup 安装时会提示
macOS	可能需要运行 xcode-select --install 安装 Xcode 命令行工具
Linux	需要安装 build-essential（Ubuntu/Debian）或等效的 GCC 工具链

---

三、⬇️ 安装 Rust 工具链

Rust 通过 rustup 进行安装和管理，这是官方推荐的方式。

3.1 📥 下载并运行 rustup

Windows 用户：

1. 访问 rustup.rs 或直接下载：
   • 64 位 (x64): rustup-init.exe
   • ARM64: rustup-init.exe
     

图 2：rustup.rs 官网可根据平台选择安装方式

2. 运行安装程序，按提示操作
3. 如果出现 "linker 'link.exe' not found" 等错误，安装程序会提示安装 Visual Studio C++ 构建工具，选择「是」即可自动安装；或手动安装 Microsoft C++ Build Tools，并勾选「Desktop development with C++」

macOS / Linux 用户：

在终端执行：

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

按提示选择默认安装即可。

3.2 ✅ 验证安装

安装完成后，务必重启终端和 VS Code，确保 PATH 已更新，然后执行：

rustc --version
cargo --version
rustup --version

若能看到版本号，说明安装成功。

图 3：在终端中验证 rustc、cargo、rustup 版本

3.3 📚 安装 rust-src 组件（重要！）

rust-analyzer 需要标准库源码才能提供完整的代码补全和跳转。执行：

rustup component add rust-src

如果遇到变量解析异常等问题，可尝试重新安装：

rustup component remove rust-src
rustup component add rust-src

3.4 🔄 更新 Rust

Rust 每 6 周发布一个稳定版，建议定期更新：

rustup update

查看本地文档（包含《Rust 程序设计语言》等）：

rustup doc

---

四、📦 Cargo 包管理器入门

在进入 VS Code 扩展配置和项目创建之前，有必要先了解 Cargo ------Rust 官方自带的包管理器和构建工具。安装 Rust 时 Cargo 会自动随 rustc 一起安装，几乎所有 Rust 项目都会使用它。

图 4：Rust 工具链：rustup 管理 rustc、cargo、rustfmt、clippy 等

4.1 📖 什么是 Cargo？

Cargo 负责：

• 创建项目 ：cargo new 生成标准项目结构
• 编译构建 ：cargo build 编译代码
• 运行项目 ：cargo run 构建并运行
• 依赖管理 ：从 crates.io 下载并管理第三方库（crate）
• 运行测试 ：cargo test
• 代码检查 ：cargo check 快速检查而不生成可执行文件

理解 Cargo 是写好 Rust 项目的前提，下面逐项介绍。

4.2 📄 Cargo.toml 清单文件详解

每个 Cargo 项目的根目录都有一个 Cargo.toml，使用 TOML 格式，定义项目元信息和依赖。

[package] 部分

定义项目基本信息，至少需要 name 和 version：

[package]
name = "hello_world"     # 项目名，编译出的可执行文件默认使用此名
version = "0.1.0"        # 语义化版本 (semver)
edition = "2021"         # Rust 版本，2015/2018/2021
authors = ["Your Name <you@example.com>"]
description = "A simple Hello World program"

常用字段说明：

字段	说明
name	项目名称，发布到 crates.io 时需唯一
version	版本号，遵循 x.y.z 格式
edition	Rust 版本，影响语法和特性
authors	作者列表
description	项目简介
license	开源协议，如 MIT、Apache-2.0
repository	源码仓库 URL

[dependencies] 部分

声明项目依赖的第三方库，例如：

[dependencies]
serde = { version = "1.0", features = ["derive"] }
rand = "0.8"
tokio = { version = "1", features = ["full"] }

图 5：Cargo.toml 的 [package] 与 [dependencies] 结构

4.3 ➕ 添加与管理依赖

使用 cargo add（推荐）

从 Rust 1.62 起，可使用 cargo add 快速添加依赖，无需手动编辑 Cargo.toml：

# 添加最新版本的 rand
cargo add rand

# 指定版本
cargo add serde@1.0

# 添加开发/测试依赖
cargo add --dev criterion

图 6：使用 cargo add 添加依赖，Cargo.toml 会自动更新

手动编辑 Cargo.toml

在 [dependencies] 下添加一行：

[dependencies]
rand = "0.8"           # 使用 0.8.x 的最新版本
serde = "1.0"          # 使用 1.x 的最新版本
reqwest = { version = "0.11", features = ["json"] }  # 指定特性

首次执行 cargo build 时，Cargo 会从 crates.io 下载依赖并生成 Cargo.lock。

4.4 🛠️ 常用 Cargo 命令速查

命令	说明
cargo new <name>	创建新项目
cargo init	在当前目录初始化项目
cargo build	编译项目（debug 模式）
cargo build --release	发布模式编译，优化性能
cargo run	编译并运行
cargo check	快速检查语法和类型，不生成可执行文件
cargo test	运行测试
cargo add <crate>	添加依赖
cargo update	更新 Cargo.lock 中的依赖版本
cargo doc --open	生成并打开项目文档
cargo fmt	格式化代码（调用 rustfmt）
cargo clippy	运行 Clippy 检查

图 7：Cargo 开发流程：new → add → build/check → run/test

4.5 🔒 Cargo.toml 与 Cargo.lock 的区别

文件	谁维护	作用
Cargo.toml	开发者手写	声明项目信息和依赖的版本要求 （如 rand = "0.8"）
Cargo.lock	Cargo 自动生成	锁定依赖的精确版本，保证可复现构建

• 库项目 ：通常将 Cargo.lock 加入 .gitignore，由使用者决定依赖版本
• 可执行程序/应用 ：建议提交 Cargo.lock，确保所有环境使用相同依赖版本

执行 cargo update 可更新 Cargo.lock 中的版本（在 Cargo.toml 允许的范围内）。

---

五、🔌 安装 rust-analyzer 扩展

5.1 📦 安装步骤

1. 打开 VS Code，按 Ctrl+Shift+X（macOS: Cmd+Shift+X）打开扩展视图
2. 搜索 rust-analyzer
3. 找到由 The Rust Programming Language 发布的扩展，点击安装
4. 安装 Release Version （稳定版）即可，除非你需要体验最新特性
   

图 8：在扩展市场中搜索并安装 rust-analyzer

⚠️ 注意 ：市场中还有另一个扩展 rust-lang.rust，该扩展已弃用，请务必使用 rust-analyzer。

5.2 🗑️ 卸载旧版 Rust 扩展

如果之前安装过旧的 Rust 扩展（rust-lang.rust），请先卸载，否则可能与 rust-analyzer 冲突。

5.3 ⏳ 首次加载

首次打开 Rust 项目时，rust-analyzer 会在左下角状态栏显示索引进度。等待其完成后再使用代码补全和跳转，效果最佳。

图 9：rust-analyzer 在状态栏显示索引进度

---

六、🎯 创建你的第一个 Rust 项目

6.1 🆕 使用 Cargo 创建项目

在终端中执行：

cargo new hello_world
cd hello_world
code .

cargo new 会创建：

• src/main.rs：入口文件，包含 main() 函数
• Cargo.toml：项目配置与依赖声明
• .gitignore：Git 忽略配置

6.2 📁 项目结构

hello_world/
├── src/
│   └── main.rs      # 主程序
├── Cargo.toml       # 项目清单
└── .gitignore

图 10：cargo new 创建的项目目录结构

默认的 main.rs 内容：

fn main() {
    println!("Hello, world!");
}

6.3 ▶️ 构建与运行

在 VS Code 集成终端（``Ctrl+```）中：

# 构建
cargo build

# 运行
cargo run

构建产物位于 target/debug/ 目录。

图 11：cargo build 编译成功与 cargo run 运行输出

---

七、⚡ rust-analyzer 核心功能

7.1 💡 IntelliSense 代码补全

图 12：rust-analyzer 提供的代码补全与 Inlay 类型提示

• 输入时自动弹出补全建议
• 支持自动导入（use 语句）
• 可按 Ctrl+Space 手动触发补全

7.2 📌 Inlay 类型提示

变量、参数、闭包等会显示推断出的类型，帮助理解代码。可在 VS Code 设置中搜索「Inlay Hints」调整显示方式。

7.3 🖱️ 悬停文档

鼠标悬停在函数、类型、变量上即可查看文档和签名。

7.4 🧭 代码导航

功能	快捷键
转到定义	F12
查看定义（peek）	Alt+F12
查找引用	Shift+F12
调用层次结构	Shift+Alt+H
工作区符号搜索	Ctrl+T
当前文件符号	Ctrl+Shift+O

7.5 ✏️ 重命名与重构

• 将光标放在变量或函数上，按 F2 可重命名，所有引用会同步更新
• 使用 Ctrl+. 可触发快速修复（Quick Fix），如添加缺失的 use、修正类型等

7.6 🎨 代码格式化

按 Shift+Alt+F （macOS: Shift+Option+F）格式化当前文件。可启用「Format On Save」实现保存时自动格式化。

7.7 🔍 Linting：启用 Clippy

默认使用 cargo check 进行诊断。要使用更严格的 Clippy：

1. 打开设置（Ctrl+,）
2. 搜索 rust-analyzer.check.command
3. 将值改为 clippy

或在 settings.json 中添加：

{
  "rust-analyzer.check.command": "clippy"
}

7.8 ▶️ CodeLens 与调试入口

在 main() 或测试函数上方会显示 Run 和 Debug 按钮，可直接运行或启动调试。

图 13：main 函数上方的 Run | Debug CodeLens

---

八、🐛 配置调试环境

8.1 🔌 安装调试扩展

根据系统选择其一：

平台	推荐扩展
Windows	Microsoft C/C++
macOS / Linux	CodeLLDB

在扩展市场搜索并安装即可。未安装时，尝试调试会收到 rust-analyzer 的提示。

8.2 📍 启用「在任何位置设置断点」

1. 打开设置，搜索 Breakpoints Everywhere
2. 勾选 Debug: Allow Breakpoints Everywhere

8.3 ▶️ 使用 rust-analyzer 自带的调试

1. 在 println! 等行左侧行号处点击，设置断点（红点）
2. 点击 main() 上方的 Debug CodeLens，或按 Ctrl+Shift+P 运行 Rust Analyzer: Debug

图 14：在 main.rs 中设置断点并启动调试

---

九、❓ 常见问题与解决方案

9.1 🔗 linker 'link.exe' not found（Windows）

原因：缺少 C/C++ 链接器。

解决 ：安装 Microsoft C++ Build Tools，选择「Desktop development with C++」工作负载。还有 Windows SDK

9.2 📦 rust-analyzer 无补全或报错「can't find Cargo.toml」

• 确保在项目根目录 （含 Cargo.toml 的文件夹）打开 VS Code
• 等待 rust-analyzer 索引完成（看左下角状态）
• 检查是否安装了 rust-src：rustup component add rust-src

9.3 🔧 变量/类型解析异常

可能是 sysroot 或 rust-src 损坏，可尝试：

rustup component remove rust-src
rustup component add rust-src

9.4 ⚠️ 扩展与内置 rust-analyzer 冲突

若通过 cargo install rust-analyzer 安装了独立二进制，且 PATH 中 ~/.cargo/bin 靠前，可能优先使用系统安装的版本。建议使用扩展自带的 server，或将 ~/.cargo/bin 中可能导致冲突的二进制重命名或移除。

9.5 📂 中文路径或特殊字符问题

尽量将项目放在英文路径下，避免因路径编码导致的异常。

9.6 🐢 性能慢、占用高

• 大型工作区可考虑使用 rust-analyzer.linkedProjects 只分析部分 crate
• 关闭 rust-analyzer.checkOnSave 可减轻保存时的负担（不推荐长期关闭）
• 将 target/ 加入 files.watcherExclude，减少文件监控

---

十、📖 学习资源

• The Rust Programming Language（官方书）
• Rust by Example
• rust-analyzer 用户手册
• Cargo 官方手册（深入 Cargo 与依赖管理）

---

十一、✅ 总结

完成本指南后，你应该已经具备：

• 使用 rustup 安装的 Rust 工具链
• 安装并配置好的 rust-analyzer 扩展
• 可用的调试环境（CodeLLDB 或 C++ 扩展）
• 对代码补全、跳转、重构等功能的了解
• 常见问题的排查思路

接下来可以专注于学习 Rust 语法和生态，在 VS Code 中愉快地编写和调试 Rust 代码。如有问题，可查阅 rust-analyzer 文档 或在相关社区提问。

---