# Rust 安装卡住？配置国内镜像解决（Windows）
> 适用场景：运行 `rustup-init.exe` 时长时间卡在
> `info: syncing channel updates for stable-x86_64-pc-windows-msvc`
---
## 1. 问题现象与原因
**现象**：rustup 安装过程中卡在 `syncing channel updates` 步骤，长时间无进度。
**原因**：rustup 需要从 `static.rust-lang.org` 下载工具链发布清单（manifest）和安装包，
该域名在国内直连速度极慢或不稳定，导致下载无响应。
**解决思路**：通过环境变量让 rustup 走国内镜像；同时给 cargo 配置 crates.io 镜像，
避免后续 `cargo build` 下载依赖时再次卡住。
---
## 2. 方案概述
| 项目 | 镜像 | 说明 |
|------|------|------|
| rustup 工具链下载 | [rsproxy.cn](https://rsproxy.cn)（主）/ 清华 TUNA（备） | 通过环境变量配置 |
| cargo 依赖（crates.io） | rsproxy.cn sparse 索引 | 通过 `~/.cargo/config.toml` 配置 |
---
## 3. 配置 rustup 镜像（安装工具链用）
rustup 通过两个环境变量决定下载源：
| 环境变量 | 含义 | rsproxy.cn 值 |
|----------|------|---------------|
| `RUSTUP_DIST_SERVER` | 工具链安装包下载地址 | `https://rsproxy.cn` |
| `RUSTUP_UPDATE_ROOT` | 发布清单（manifest）地址 | `https://rsproxy.cn/rustup` |
### 3.1 永久生效（推荐，CMD / PowerShell / Git Bash 均可执行）
```bat
setx RUSTUP_DIST_SERVER "https://rsproxy.cn"
setx RUSTUP_UPDATE_ROOT "https://rsproxy.cn/rustup"
setx写入用户环境变量（HKCU\Environment），对之后新开的终端窗口永久生效。
输出成功: 指定的值已得到保存。即配置成功。
注意：当前已打开的窗口不会生效，需新开终端。
3.2 当前会话临时生效（仅当前窗口，适合快速验证）
:: CMD
set RUSTUP_DIST_SERVER=https://rsproxy.cn
set RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
# PowerShell
$env:RUSTUP_DIST_SERVER = "https://rsproxy.cn"
$env:RUSTUP_UPDATE_ROOT = "https://rsproxy.cn/rustup"
# Git Bash
export RUSTUP_DIST_SERVER=https://rsproxy.cn
export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
3.3 验证镜像可访问
curl -sI -m 15 https://rsproxy.cn/rustup/release-stable.toml | head -3
# 返回 HTTP/1.1 200 OK 即正常
4. 配置 cargo 镜像（下载依赖用）
在 %USERPROFILE%\.cargo\config.toml（即 C:\Users\<用户名>\.cargo\config.toml）写入：
# crates.io 国内镜像 (rsproxy.cn)
[source.crates-io]
replace-with = "rsproxy-sparse"
[source.rsproxy-sparse]
registry = "sparse+https://rsproxy.cn/index/"
[registries.rsproxy]
index = "sparse+https://rsproxy.cn/index/"
[net]
git-fetch-with-cli = true
文件不存在则新建。sparse 索引需要 cargo 1.68+，当前 stable 均满足。
5. 重新执行安装
-
关掉卡住的安装窗口：在原窗口按
Ctrl+C，或直接关闭该窗口。
（可先用tasklist | grep -i rustup确认没有残留的rustup-init.exe进程，有则
taskkill /F /IM rustup-init.exe） -
新开一个终端（让上一步
setx的环境变量生效）。 -
重新运行安装程序（路径换成你自己的）：
F:\download\rustup-init.exe或跳过交互直接默认安装：
F:\download\rustup-init.exe -y安装程序会从断点续传，走镜像后通常几分钟内完成。
-
验证安装：
rustup show rustc --version cargo --version
6. 常见问题
6.1 rsproxy.cn 不稳定，改用清华 TUNA
setx RUSTUP_DIST_SERVER "https://mirrors.tuna.tsinghua.edu.cn/rustup"
setx RUSTUP_UPDATE_ROOT "https://mirrors.tuna.tsinghua.edu.cn/rustup"
config.toml 相应改为：
[source.crates-io]
replace-with = "tuna"
[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"
6.2 如何删除镜像环境变量
setx 不支持直接删除，两种方式：
-
图形界面：
Win+R→sysdm.cpl→ 高级 → 环境变量 → 用户变量中删除 -
命令行（注册表删除）：
reg delete "HKCU\Environment" /v RUSTUP_DIST_SERVER /f reg delete "HKCU\Environment" /v RUSTUP_UPDATE_ROOT /f
6.3 编译报错找不到 link.exe
x86_64-pc-windows-msvc 工具链编译时需要 MSVC 链接器。安装
Visual Studio Build Tools，
勾选「使用 C++ 的桌面开发」工作负载即可。
6.4 换镜像后仍卡
- 确认环境变量已生效：
echo %RUSTUP_DIST_SERVER%（CMD）或echo $env:RUSTUP_DIST_SERVER（PowerShell） - 确认
setx后是新开的终端 - 删除
%USERPROFILE%\.rustup\downloads下的残留缓存后重试
7. 参考链接
- rsproxy.cn 官网：https://rsproxy.cn/
- 清华 TUNA rustup 镜像帮助：https://mirrors.tuna.tsinghua.edu.cn/help/rustup/
- 清华 TUNA crates.io 镜像帮助：https://mirrors.tuna.tsinghua.edu.cn/help/crates.io-index/