当前位置：首页 > news >正文

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

news 2025/9/12 5:52:07

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 安装流程

下载安装器

# 官方方式（可能很慢）
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，按提示安装。

配置环境变量
安装后，Rust 工具链默认会放在：
```
C:\Users\<用户名>\.cargo\bin
```
确保这个路径已经加入到 PATH。
验证安装
```
rustc --version
cargo --version
```

三、macOS 安装流程

使用 Homebrew 安装依赖
```
brew install rustup-init
rustup-init
```

配置国内镜像（推荐在 .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

初始化环境

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

四、Linux 安装流程

Linux 用户建议直接用 rustup：

下载安装脚本

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

配置国内镜像（推荐写入 ~/.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

加载环境变量并验证

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

五、配置 crates.io 国内源

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

全局配置
编辑 $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 镜像。

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

六、常见问题与避坑指南

cargo build 卡死在下载依赖
→ 确认 .cargo/config.toml 已正确配置镜像，尤其是 [source.crates-io] replace-with。
Windows PowerShell 环境变量不生效
→ 需要在系统级环境变量里写入，重启 PowerShell。
不同项目需要不同版本 Rust
→ 用 rustup override set stable 或 rustup override set nightly 来指定项目使用的工具链。
升级慢或失败
→ 换成中科大或清华镜像，更新时加 RUSTUP_DIST_SERVER 环境变量。