02 - Rust 安装教程

面向零基础到进阶开发者，全流程以表格呈现。统一使用官方工具链管理器 rustup，可同时管理 stable / beta / nightly 与交叉编译目标。
文档更新时间：2026-11-02

1. 三平台安装方式总览

平台	推荐方式	安装命令 / 入口	默认工具链	必需的前置组件
Windows 10/11	官方 `rustup-init.exe`（推荐）或 `winget`	访问 https://rustup.rs 下载运行 `winget install Rustlang.Rustup`	`x86_64-pc-windows-msvc`	Visual Studio 生成工具（C++ 桌面开发工作负载）
Windows（备选）	WSL2 + Ubuntu	在 WSL 内执行 Linux 安装命令	`x86_64-unknown-linux-gnu`	`build-essential`
macOS（Intel / Apple Silicon）	官方脚本	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \\| sh`	`x86_64-apple-darwin` `aarch64-apple-darwin`	`xcode-select --install`（命令行工具，提供 linker）
Linux（Debian/Ubuntu）	官方脚本	同上；或 `apt install rustup`	`x86_64-unknown-linux-gnu`	`build-essential`（gcc / linker）
Linux（Fedora/RHEL）	官方脚本 / dnf	`dnf install rustup cargo` 或官方脚本	同上	`dnf groupinstall "Development Tools"`
Linux（Arch）	pacman	`pacman -S rustup`	同上	`base-devel`
通用容器/CI	官方 Docker 镜像	`docker run --rm -it rust:latest`	镜像内置	无

为什么不直接用系统包管理器装 rustc？系统仓库版本通常滞后，且与 rustup 并存容易产生 PATH 冲突。统一交给 rustup 管理最省心。

2. Windows 安装步骤

步骤	操作	说明 / 备注
① 装 C++ 生成工具	下载 Visual Studio Build Tools，勾选 "使用 C++ 的桌面开发"	只需 MSVC 生成工具 + Windows SDK，约占 4–7 GB；可只勾 MSVC v143 与对应 SDK
② 下载 rustup	https://rustup.rs → 下载 `rustup-init.exe`（64 位）	也可用 `winget install Rustlang.Rustup`
③ 运行安装器	双击运行，按提示选择 `1) Proceed with installation (default)`	默认安装 `stable` + `x86_64-pc-windows-msvc`
④ 验证环境	重新打开 PowerShell / 终端	安装器已写入 `%USERPROFILE%\.cargo\bin` 到 PATH
⑤ 验证命令	`rustc --version`、`cargo --version`、`rustup show`	三者都有输出即成功
备选：GNU 工具链	安装时选 `x86_64-pc-windows-gnu`	rustup 自带 MinGW 链接器，可免装 MSVC，但与部分 Windows 生态库兼容性略差
备选：WSL2	`wsl --install` → 在 Ubuntu 内按 Linux 步骤安装	项目文件放在 WSL 文件系统内（`~/`），不要放 `/mnt/c`，否则编译极慢

Windows 常见坑

现象	原因	解决
`linker 'link.exe' not found`	未装 MSVC 生成工具	补装 C++ 桌面开发工作负载，重启终端
`'cargo' 不是内部或外部命令`	PATH 未生效	重启终端；检查 `%USERPROFILE%\.cargo\bin` 是否在 PATH
安装器卡在下载	境外源慢	见第 6 节镜像加速
VS Code 中 rust-analyzer 找不到 cargo	GUI 启动时未加载 PATH	从终端 `code .` 启动，或在设置中指定 `rust-analyzer.server.path`
杀软/Defender 拖慢编译	实时扫描	将项目目录与 `~/.cargo` 加入排除项

3. macOS 安装步骤

步骤	操作	说明
① 安装命令行工具	`xcode-select --install`	提供 `cc` linker；Xcode 已安装则可跳过
② 安装 rustup	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \\| sh`	按提示回车使用默认配置
③ 生效环境变量	`source "$HOME/.cargo/env"` （zsh 默认已写入 `~/.zshrc`，新开终端即可）	macOS 默认 shell 为 zsh
④ 验证	`rustc --version && cargo --version && rustup show`	Apple Silicon 显示 `aarch64-apple-darwin`
备选：Homebrew	`brew install rustup-init && rustup-init`	不建议 `brew install rust`，会与 rustup 版本管理冲突
交叉编译 iOS	`rustup target add aarch64-apple-ios aarch64-apple-ios-sim`	移动端开发需要

4. Linux 安装步骤

发行版	安装前置依赖	安装 Rust
Debian / Ubuntu	`sudo apt update && sudo apt install -y build-essential curl`	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \\| sh`
Fedora / RHEL / CentOS	`sudo dnf groupinstall -y "Development Tools"`	同上（或 `sudo dnf install rustup cargo`）
Arch / Manjaro	`sudo pacman -S --needed base-devel`	`sudo pacman -S rustup` → `rustup default stable`
openSUSE	`sudo zypper install -t pattern devel_basis`	官方脚本
Alpine（musl）	`apk add build-base`	官方脚本；静态链接常用 `x86_64-unknown-linux-musl`

安装后执行 source "$HOME/.cargo/env" 或重开终端，再运行 rustc --version 验证。

5. 安装后的验证与首个项目

命令	作用
`rustc --version`	查看编译器版本
`cargo --version`	查看包管理器版本
`rustup show`	查看当前工具链、已装 target 与 profile
`rustup show home`	查看 `RUSTUP_HOME` 路径
`cargo new hello-rust`	创建项目（加 `--lib` 建库）
`cd hello-rust && cargo run`	编译并运行，输出 `Hello, world!`
`cargo check`	快速类型检查（不生成产物）
`rustup doc`	打开本地官方文档（离线可用）

6. 国内网络加速（镜像配置）

6.1 工具链下载镜像（环境变量）

镜像	`RUSTUP_DIST_SERVER`	`RUSTUP_UPDATE_ROOT`
RsProxy（字节，推荐）	`https://rsproxy.cn`	`https://rsproxy.cn/rustup`
清华 TUNA	`https://mirrors.tuna.tsinghua.edu.cn/rustup`	`https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup`
中科大 USTC	`https://mirrors.ustc.edu.cn/rust-static`	`https://mirrors.ustc.edu.cn/rust-static/rustup`
阿里云	`https://mirrors.aliyun.com/rust-static`	`https://mirrors.aliyun.com/rust-static/rustup`

临时生效（安装前执行一次即可）：

 # Linux / macOS
 export RUSTUP_DIST_SERVER=https://rsproxy.cn
 export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

 # Windows PowerShell
 $env:RUSTUP_DIST_SERVER='https://rsproxy.cn'
 $env:RUSTUP_UPDATE_ROOT='https://rsproxy.cn/rustup'
 .\rustup-init.exe

永久生效：Linux/macOS 写入 ~/.bashrc 或 ~/.zshrc；Windows 在「系统属性 → 环境变量」中新增。

6.2 依赖下载镜像（`~/.cargo/config.toml`）

平台	配置文件路径
Linux / macOS	`~/.cargo/config.toml`
Windows	`%USERPROFILE%\.cargo\config.toml`

 [source.crates-io]
 replace-with = "rsproxy-sparse"
 
 [source.rsproxy-sparse]
 registry = "sparse+https://rsproxy.cn/index/"
 
 [registries.rsproxy]
 index = "https://rsproxy.cn/crates.io-index/"
 
 [net]
 git-fetch-with-cli = true

备选源（替换 replace-with 为目标名即可）：

镜像	sparse 索引地址
清华 TUNA	`sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/`
中科大 USTC	`sparse+https://mirrors.ustc.edu.cn/crates.io-index/`
上海交大 SJTUG	`sparse+https://mirrors.sjtug.sjtu.edu.cn/crates.io-index/`

sparse 协议只下载所需 crate 的索引，比传统 git 索引快很多（Rust 1.68+ 默认）。git-fetch-with-cli = true 可规避部分网络环境的 SSL 证书问题。
若使用 HTTP 代理：~/.cargo/config.toml 中加 [http] proxy = "http://127.0.0.1:7890"。

7. rustup 常用命令

命令	作用
`rustup update`	更新已安装工具链（6 周一次新版本）
`rustup default stable`	设定默认工具链
`rustup toolchain install nightly`	安装 nightly
`rustup toolchain list`	列出已装工具链
`rustup override set nightly`	为当前目录指定工具链（写入 `rust-toolchain.toml` 更推荐）
`rustup target add <triple>`	添加交叉编译目标，如 `aarch64-unknown-linux-gnu`
`rustup component add rustfmt clippy rust-src`	装格式化、lint 与标准库源码
`rustup component add rust-analyzer`	部分场景需单独安装语言服务器（新版已随组件提供）
`rustup which cargo`	查看实际调用的 cargo 路径（排查 PATH 冲突）
`rustup self uninstall`	完全卸载 rustup 与工具链
`cargo +nightly build`	临时使用指定工具链

关键目录与环境变量

变量 / 目录	默认值	用途
`CARGO_HOME`	`~/.cargo`	存放 cargo 二进制、registry 缓存、`config.toml`
`RUSTUP_HOME`	`~/.rustup`	存放各版本工具链
`PATH` 追加项	`~/.cargo/bin`	使 `cargo` / `rustc` / `rustup` 全局可用
项目文件	`Cargo.toml` / `Cargo.lock`	依赖清单与版本锁

8. IDE 选型对比

IDE / 编辑器	费用	Rust 支持方式	优势	不足	适合人群
VS Code + rust-analyzer	免费	官方 LSP 插件	官方推荐、生态最大、轻量、插件丰富、跨平台一致	大项目索引较吃资源，重构能力弱于 JetBrains	绝大多数人的首选，新手到进阶通用
RustRover（JetBrains）	非商业用途免费；商业订阅约 ¥550/年	原生内置	开箱即用：调试器、Cargo 集成、数据库、重构、性能分析最强	内存占用高、启动慢、需登录 JetBrains 账号	重度工程化、企业级项目、习惯 JetBrains 快捷键
CLion + Rust 插件	付费（订阅）	插件	C/C++ 与 Rust 混合项目的最佳选择	价格高	做 FFI / 混合语言开发
IntelliJ IDEA Ultimate + Rust 插件	付费	插件	多语言大仓项目统一工具链	价格高、Rust 体验略逊 RustRover	多语言全栈团队
Zed	免费（部分功能订阅）	内置 rust-analyzer	用 Rust 编写，启动与响应极快，协作功能强	插件生态尚在成长	追求极致速度、远程协作
Neovim + rustaceanvim	免费	LSP	完全可定制、终端内高效、资源占用低	配置成本高，需自行搭 DAP 调试	终端重度用户、Vim 党
Helix	免费	内置 LSP	零配置开箱即用（选区-动作模型）	操作模型与 Vim 不同，插件生态小	想少折腾的终端用户
Emacs（rustic / eglot）	免费	LSP	深度可定制	学习曲线陡	Emacs 老用户
Eclipse Corrosion / Theia	免费	LSP	特定生态集成	用户相对小众	有特殊集成需求

一句话建议：新手与大多数开发者选 VS Code + rust-analyzer；追求开箱即用与最强重构/调试、且符合非商业授权条件，选 RustRover；终端党选 Neovim(rustaceanvim) 或 Zed。

9. VS Code 插件推荐（重点）

必装

插件	ID	作用
rust-analyzer	`rust-lang.rust-analyzer`	官方语言服务器：补全、跳转、内联类型提示、宏展开、诊断、重构。必装
CodeLLDB	`vadimcn.vscode-lldb`	断点调试（基于 LLDB），支持变量查看、条件断点；Windows 需要 MSVC 工具链配合
Even Better TOML	`tamasfe.even-better-toml`	`Cargo.toml` 语法高亮、补全、schema 校验
crates	`serayuzgur.crates`	在 `Cargo.toml` 中显示依赖最新版本并一键升级（同类可选 `Dependi`）
Error Lens	`usernamehw.errorlens`	把编译错误/警告直接内联显示在代码行尾，调试效率显著提升

插件	作用
Rust Test Explorer / Test Lens	侧边栏可视化运行与调试 `#[test]`
rust-mod-generator	一键生成 `mod.rs` 模块树
search-crates-io	在编辑器内搜索 crates.io 并插入依赖
GitLens	Git 历史与 blame（通用）
GitHub Copilot / Codeium / 通义灵码	AI 补全（可选，注意代码合规）
Markdown All in One	写 Rust 文档注释与 README
Remote - SSH / Dev Containers / WSL	远程与容器开发环境
Todo Tree	聚合 `TODO` / `FIXME`

VS Code 关键设置（`settings.json`）

配置项	建议值	说明
`rust-analyzer.check.command`	`"clippy"`	保存时用 clippy 代替 `cargo check`，lint 更严格
`rust-analyzer.check.allTargets`	`true`	同时检查测试与示例目标
`editor.formatOnSave`	`true`	保存即 `cargo fmt`
`rust-analyzer.rustfmt.extraArgs`	`["+nightly"]`	需 nightly rustfmt 时才启用
`rust-analyzer.cargo.features`	`"all"` 或指定数组	让分析覆盖 feature 门控代码
`rust-analyzer.inlayHints.enable`	`true`	显示类型/参数名内联提示（新手强烈建议开）
`rust-analyzer.lens.enable`	`true`	显示 Run / Debug / 引用数等 CodeLens
`rust-analyzer.procMacro.enable`	`true`	展开过程宏（如 serde、tokio 宏）以获得正确提示
`rust-analyzer.server.path`	留空或指向 `rustup which rust-analyzer`	PATH 未生效时手动指定
`files.watcherExclude`	排除 `/target/`	避免文件监听耗尽句柄，大项目必备

10. 其他 IDE 配置要点

IDE	配置要点
RustRover	首次启动自动探测 rustup 工具链；内置调试器无需额外插件；`Settings → Rust` 可设定工具链、rustfmt、clippy；非商业免费需登录 JetBrains 账号，每年续期
CLion / IntelliJ	`Settings → Plugins` 安装 Rust 插件，重启后指定 toolchain 路径（`~/.cargo/bin`）；调试用捆绑的 LLDB / GDB
Neovim	插件：`rustaceanvim`（推荐）或 `nvim-lspconfig` + `mason`；调试：`nvim-dap` + `codelldb`；格式化：`null-ls` / `conform.nvim` 调 `rustfmt`；需先 `rustup component add rust-analyzer`
Zed	内置 rust-analyzer，打开项目即生效；调试需配置 `debug.json`（GDB/LLDB）
Helix	内置 LSP，安装 rust-analyzer 到 PATH 后直接用；配置 `~/.config/helix/languages.toml`
Emacs	`rustic-mode` 或 `rust-mode` + `eglot`/`lsp-mode`；`cargo-process` 提供快捷键
Web 端	Rust Playground / Rust Explorer，免安装试验代码

11. 通用安装后配置清单

项目	命令 / 操作	必要性
装格式化与 lint	`rustup component add rustfmt clippy`	必需（rustup 默认已含，可再确认）
装标准库源码	`rustup component add rust-src`	推荐（阅读源码、rust-analyzer 跳转更完整）
开启保存即格式化	IDE 设置 `formatOnSave`	推荐
配置镜像	见第 6 节	国内网络必做
装调试器	VS Code 装 CodeLLDB；Linux 确认 `gdb`/`lldb`	推荐
加快编译（可选）	`[build] rustflags = ["-C", "linker=rust-lld"]` 或使用 `mold`、`sccache`	大项目可选
配置 Git 忽略	项目 `.gitignore` 中加 `/target`	必需
试跑测试	`cargo test`	验证工具链完整

12. 常见问题排查

现象	平台	原因	解决
`linker 'cc' not found`	Linux	缺 C 编译器	`sudo apt install build-essential`（或对应发行版开发包）
`linker 'link.exe' not found`	Windows	缺 MSVC	装 Visual Studio 生成工具 → C++ 桌面开发
`cargo: command not found`	全平台	PATH 未生效	重开终端 / `source $HOME/.cargo/env` / 检查 `~/.cargo/bin`
rust-analyzer 一直 "Loading"	VS Code	索引大项目或 PATH 问题	从终端启动 `code .`；排除 `target/`；设置 `rust-analyzer.server.path`
下载依赖超时	全平台	网络	配镜像（第 6 节）或设置 `[http] proxy`
SSL 证书错误	全平台	内置 libgit2 证书问题	`[net] git-fetch-with-cli = true`
权限错误（macOS）	macOS	目录权限	检查 `~/.cargo`、`~/.rustup` 归属，勿用 `sudo` 装 rustup
编译极慢	WSL	项目在 `/mnt/c`	把项目移到 WSL 原生文件系统
依赖版本冲突	全平台	`Cargo.lock`	`cargo update -p <crate>` 或删除 lock 重生成
需要 nightly 特性	全平台	默认 stable	`rustup toolchain install nightly` + `cargo +nightly ...`
卸载重装	全平台	—	`rustup self uninstall` 后删除 `~/.cargo`、`~/.rustup` 残留

13. 推荐组合（按人群速查）

人群 / 场景	推荐组合
零基础入门	Windows/macOS + rustup(stable) + VS Code + rust-analyzer + Error Lens + CodeLLDB
学生 / 个人项目	任一平台 + VS Code 或 RustRover（非商业免费）
企业开发（商业授权）	RustRover 商业版 / CLion + Rust 插件 / VS Code
嵌入式 / 交叉编译	Linux + rustup + `rustup target add` + VS Code + `probe-rs` / `cargo-embed`
内核 / 系统底层	Linux + nightly + `rust-src` 组件 + Neovim/VS Code
WebAssembly	任一平台 + `rustup target add wasm32-unknown-unknown` + `wasm-pack` + VS Code
终端效率党	Neovim(rustaceanvim) 或 Zed + `rust-analyzer` + `codelldb`
CI / 容器	`docker run rust:latest` 或 `rust:alpine` + `cargo-chef` 缓存依赖层

14. 官方与常用链接

资源	地址
安装入口	https://rustup.rs
官方站点	https://www.rust-lang.org
官方入门书（中文）	https://doc.rust-lang.org/book/zh-cn/（或 `/book/`）
标准库文档	https://doc.rust-lang.org/std/
包仓库	https://crates.io / https://lib.rs
在线运行	https://play.rust-lang.org
rust-analyzer 手册	https://rust-analyzer.github.io/book/
RustRover 下载	https://www.jetbrains.com/rust/download
国内镜像（RsProxy）	https://rsproxy.cn
清华镜像说明	https://mirrors.tuna.tsinghua.edu.cn/help/rustup/
中科大镜像说明	https://mirrors.ustc.edu.cn/help/rustup.html

时间邮局

02 - Rust 安装教程

1. 三平台安装方式总览

2. Windows 安装步骤

Windows 常见坑

3. macOS 安装步骤

4. Linux 安装步骤

5. 安装后的验证与首个项目

6. 国内网络加速（镜像配置）

6.1 工具链下载镜像（环境变量）

6.2 依赖下载镜像（`~/.cargo/config.toml`）

7. rustup 常用命令

8. IDE 选型对比

9. VS Code 插件推荐（重点）

必装

推荐可选

VS Code 关键设置（`settings.json`）

10. 其他 IDE 配置要点

11. 通用安装后配置清单

12. 常见问题排查

13. 推荐组合（按人群速查）

14. 官方与常用链接

时间邮局

02 - Rust 安装教程

1. 三平台安装方式总览

2. Windows 安装步骤

Windows 常见坑

3. macOS 安装步骤

4. Linux 安装步骤

5. 安装后的验证与首个项目

6. 国内网络加速（镜像配置）

6.1 工具链下载镜像（环境变量）

6.2 依赖下载镜像（~/.cargo/config.toml）

7. rustup 常用命令

8. IDE 选型对比

9. VS Code 插件推荐（重点）

必装

推荐可选

VS Code 关键设置（settings.json）

10. 其他 IDE 配置要点

11. 通用安装后配置清单

12. 常见问题排查

13. 推荐组合（按人群速查）

14. 官方与常用链接

支持与分享

6.2 依赖下载镜像（`~/.cargo/config.toml`）

VS Code 关键设置（`settings.json`）