Rust 开发环境安装与 crates.io 国内源配置（Windows / macOS / Linux 全流程）

Rust 这几年在系统编程、WebAssembly、区块链、后端服务领域越来越火，很多开发者都在尝试用它做一些新项目。
但是国内安装 Rust 开发环境时，经常遇到 安装慢、依赖拉不下来、crates.io 超时 等问题。本文结合个人踩坑经验，整理了一份 跨平台（Windows / macOS / Linux）全流程安装与镜像配置指南，希望能帮到后来人。

一、安装方式对比

Rust 的官方推荐安装方式是通过 rustup，它不仅能帮你安装编译器 rustc，还可以管理多个版本、安装 cargo 包管理工具。

常见安装路径：

• 官方 rustup-init
  跨平台支持最好，但国内下载速度比较慢。

• 国内镜像站
  比如清华、中科大等高校镜像源，下载速度更快。

• 包管理器
  macOS 用户可以用 brew，Linux 可以用 apt/yum/dnf，Windows 可以用 scoop/choco，但更新往往不如 rustup 及时。

建议新手直接用 rustup，方便切换版本和管理工具链。

二、Windows 安装流程

1. 下载安装器

   # 官方方式（可能很慢）
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o rustup-init.exe
   .\rustup-init.exe
   
   # 推荐使用清华镜像加速
   set RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
   set RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
   

   然后运行 rustup-init.exe，按提示安装。

2. 配置环境变量
   安装后，Rust 工具链默认会放在：

   C:\Users\<用户名>\.cargo\bin
   

   确保这个路径已经加入到 PATH。

3. 验证安装

   rustc --version
   cargo --version
   

三、macOS 安装流程

1. 使用 Homebrew 安装依赖

   brew install rustup-init
   rustup-init
   

2. 配置国内镜像（推荐在 .zshrc 或 .bashrc 中写入）：

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

3. 初始化环境

   source $HOME/.cargo/env
   rustc --version
   cargo --version
   

四、Linux 安装流程

Linux 用户建议直接用 rustup：

1. 下载安装脚本

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

2. 配置国内镜像（推荐写入 ~/.bashrc 或 ~/.zshrc）：

   export RUSTUP_DIST_SERVER=https://mirrors.tuna.tsinghua.edu.cn/rustup
   export RUSTUP_UPDATE_ROOT=https://mirrors.tuna.tsinghua.edu.cn/rustup/rustup
   

3. 加载环境变量并验证

   source $HOME/.cargo/env
   rustc --version
   cargo --version
   

五、配置 crates.io 国内源

Rust 的依赖管理通过 cargo 完成，默认从 crates.io 下载。但国内访问经常超时，需要配置镜像源。

1. 全局配置
   编辑 $HOME/.cargo/config.toml（没有就新建）：

   [source.crates-io]
   replace-with = 'ustc'
   
   [source.ustc]
   registry = "https://mirrors.ustc.edu.cn/crates.io-index"
   
   [net]
   git-fetch-with-cli = true  # 避免部分环境下 libgit2 超时
   

   这样所有项目都会走 USTC 镜像。

2. 单项目配置
   如果只想在某个项目用镜像，可以在项目根目录新建 .cargo/config.toml 文件，写入相同内容。

六、常见问题与避坑指南

1. cargo build 卡死在下载依赖
   → 确认 .cargo/config.toml 已正确配置镜像，尤其是 [source.crates-io] replace-with。

2. Windows PowerShell 环境变量不生效
   → 需要在系统级环境变量里写入，重启 PowerShell。

3. 不同项目需要不同版本 Rust
   → 用 rustup override set stable 或 rustup override set nightly 来指定项目使用的工具链。

4. 升级慢或失败
   → 换成中科大或清华镜像，更新时加 RUSTUP_DIST_SERVER 环境变量。

Rust 的安装与环境配置本身不复杂，真正的难点在于 国内网络环境 导致下载缓慢或失败。
建议：

• 安装器 用 rustup，方便版本管理；

• 镜像源 配置清华/中科大镜像，加速 crates 下载；

• 跨平台 建议写好 ~/.cargo/config.toml，不管在哪台机器都能统一使用。

这样一套配置下来，基本可以保证在 Windows / macOS / Linux 下都有顺畅的开发体验。