Rust 开发环境搭建完全指南

> 分类：环境配置 | 平台：macOS + Linux | 难度：⭐⭐

![Rust 工具链架构](/media/202605/2026-05-17_011641_1204470.7097765377512275.png)

## 目标环境

最终效果——终端执行以下命令，全部正常输出即搭建完成：

```bash
rustc --version    # rustc 1.87.0+
cargo --version    # cargo 1.87.0+
rustup show        # 显示已安装的 toolchain
```

| 组件 | 版本要求 | 说明 |
|------|---------|------|
| rustup | latest | Rust 工具链管理器 |
| rustc | 1.77+ | Rust 编译器 |
| cargo | 1.77+ | 包管理器 + 构建系统 |
| rust-analyzer | latest | LSP 语言服务器 |

## 系统要求

- **macOS**：10.15+ (Catalina)，需安装 Xcode Command Line Tools
- **Linux**：glibc 2.31+ 或 musl libc，需 gcc / make / pkg-config
- **磁盘空间**：~1.5 GB（stable toolchain + 标准库 + 文档）
- **网络**：首次安装需访问 static.rust-lang.org

## 安装步骤

![安装流程图](/media/202605/2026-05-17_011641_8666470.7411830811357535.png)

### Step 1: 安装 rustup

rustup 是 Rust 官方工具链管理器，一条命令搞定：

```bash
# macOS / Linux 通用
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

安装脚本会交互式询问安装选项，默认选择 `1) Proceed with installation` 即可。

**非交互式安装**（适合 CI/自动化）：

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

### Step 2: 配置环境变量

安装完成后，需要加载 PATH：

```bash
source $HOME/.cargo/env
```

建议将以下内容写入 `~/.bashrc` 或 `~/.zshrc` 使其永久生效：

```bash
# Rust
. "$HOME/.cargo/env"
```

验证：

```bash
rustup --version   # rustup 1.28+
which rustc        # ~/.cargo/bin/rustc
```

### Step 3: 安装 stable toolchain

rustup 默认已安装 stable，确认并更新：

```bash
rustup toolchain list
rustup toolchain install stable
rustup default stable
rustc --version
cargo --version
```

**安装额外 target**（交叉编译）：

```bash
rustup target add x86_64-pc-windows-gnu
rustup target add aarch64-unknown-linux-gnu
```

### Step 4: 安装常用组件

```bash
rustup component add rust-analyzer  # LSP（IDE 必装）
rustup component add rustfmt        # 格式化
rustup component add clippy         # Lint
rustup component add rust-src       # 标准库源码（IDE 跳转）
rustup component list --installed
```

### Step 5: IDE 配置

#### VS Code（推荐）

1. 安装扩展 **rust-analyzer**（不是旧版 Rust 扩展）
2. 可选：CodeLLDB（调试）、Even Better TOML、crates（依赖版本提示）

#### RustRover（JetBrains）

JetBrains 出品的 Rust 专用 IDE，内置工具链管理，免费非商业版可用。

#### Neovim

使用 rustaceanvim 插件即可获得完整 IDE 体验。

### Step 6: 第一个项目

```bash
cargo new hello_rust
cd hello_rust
cargo run
# -> Hello, world!
```

## Cargo 生态与常用命令

![Cargo 生态](/media/202605/2026-05-17_011642_3051850.01307413997046658.png)

| 命令 | 用途 | 示例 |
|------|------|------|
| cargo build | 编译项目 | cargo build --release |
| cargo run | 编译并运行 | cargo run -- arg1 |
| cargo check | 快速类型检查 | 日常开发首选 |
| cargo test | 运行测试 | cargo test -- --nocapture |
| cargo add | 添加依赖 | cargo add serde -F derive |
| cargo doc | 生成文档 | cargo doc --open |
| cargo clippy | 代码 lint | cargo clippy -- -W clippy::all |
| cargo fmt | 格式化代码 | cargo fmt --check（CI 用） |
| cargo publish | 发布到 crates.io | cargo publish --dry-run |

**推荐依赖**：

```toml
[dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"
clap = { version = "4", features = ["derive"] }
tracing = "0.1"
```

## 常见问题 FAQ

### Q: 安装报错 rustup could not set default toolchain

可能是网络问题，设置镜像源（国内推荐）：

```bash
export RUSTUP_DIST_SERVER=https://mirrors.ustc.edu.cn/rust-static
export RUSTUP_UPDATE_ROOT=https://mirrors.ustc.edu.cn/rust-static/rustup
```

### Q: macOS 编译报 linker 'cc' not found

```bash
xcode-select --install
```

### Q: Linux 编译报 linker 'cc' not found

```bash
sudo apt install build-essential   # Debian/Ubuntu
sudo dnf install gcc               # Fedora
```

### Q: 如何切换 nightly / stable？

```bash
rustup toolchain install nightly
rustup default nightly        # 全局切换
rustup override set nightly   # 仅当前目录
```

### Q: 如何更新 Rust？

```bash
rustup update                 # 更新所有 toolchain
rustup self update            # 更新 rustup 自身
```

### Q: VS Code rust-analyzer 报错 server not started

1. 确认已安装：`rustup component add rust-analyzer`
2. 重启 VS Code
3. 检查输出面板：View -> Output -> rust-analyzer

## 卸载/清理

```bash
rustup self uninstall                           # 完全卸载
rustup toolchain uninstall nightly-x86_64-...   # 删除指定 toolchain
cargo cache -a                                   # 清理缓存（需 cargo install cargo-cache）
rm -rf ~/.cargo/registry/cache                   # 手动清理
rm -rf ~/.rustup/toolchains
```

## 速查清单

```
[x] rustup 安装完成       -> rustup --version
[x] stable toolchain 就绪  -> rustc --version
[x] cargo 可用            -> cargo --version
[x] rust-analyzer 已安装   -> rustup component list
[x] IDE 配置完成          -> 代码补全/跳转正常
[x] 第一个项目运行成功     -> cargo new && cargo run
```