国内镜像源配置 ​

为什么需要镜像源 ​

Rust 的官方服务器(static.rust-lang.org 和 crates.io)部署在国外,国内直接访问时经常遇到下载慢、连接超时甚至完全无法连接的情况。这会影响两个方面:一是通过 Rustup 安装和更新工具链时下载编译器组件很慢,二是通过 Cargo 下载依赖 crate 时速度不理想。配置国内镜像源可以把这些下载请求指向国内的镜像服务器,速度提升非常明显。

需要配置的两个部分 ​

Rust 的镜像配置分为两块,它们是独立的,需要分别设置:

配置目标作用配置方式
Rustup 镜像加速工具链、编译器、组件的下载设置环境变量
Cargo 镜像(crates.io)加速第三方 crate 依赖的下载编辑配置文件

配置 Rustup 镜像 ​

Rustup 通过两个环境变量来控制下载源:

  • RUSTUP_DIST_SERVER:工具链和组件的下载地址
  • RUSTUP_UPDATE_ROOT:Rustup 自身更新的下载地址

Windows(PowerShell) ​

powershell
# 临时设置(只对当前 PowerShell 窗口有效)
$ENV:RUSTUP_DIST_SERVER = 'https://mirrors.ustc.edu.cn/rust-static'
$ENV:RUSTUP_UPDATE_ROOT = 'https://mirrors.ustc.edu.cn/rust-static/rustup'

# 设置好后就可以执行安装或更新操作了
rustup update

如果想永久生效,需要把这两个变量添加到系统环境变量中:

powershell
# 永久设置用户级环境变量(需要重新打开 PowerShell 才生效)
[System.Environment]::SetEnvironmentVariable('RUSTUP_DIST_SERVER', 'https://mirrors.ustc.edu.cn/rust-static', 'User')
[System.Environment]::SetEnvironmentVariable('RUSTUP_UPDATE_ROOT', 'https://mirrors.ustc.edu.cn/rust-static/rustup', 'User')

也可以手动操作:右键"此电脑" -> 属性 -> 高级系统设置 -> 环境变量,在用户变量中新增这两个变量。

macOS / Linux(Bash / Zsh) ​

bash
# 在 ~/.bashrc 或 ~/.zshrc 末尾添加以下两行
export RUSTUP_DIST_SERVER="https://mirrors.ustc.edu.cn/rust-static"
export RUSTUP_UPDATE_ROOT="https://mirrors.ustc.edu.cn/rust-static/rustup"

# 使配置立即生效
source ~/.bashrc
# 或
source ~/.zshrc

配置 Cargo 镜像(crates.io 源替换) ​

Cargo 的镜像配置写在 ~/.cargo/config.toml 文件中(如果文件不存在需要手动创建)。

Windows 上这个文件的完整路径通常是 C:\Users\你的用户名\.cargo\config.toml。

使用中科大源(推荐) ​

toml
# ~/.cargo/config.toml

[source.crates-io]
# 替换 crates.io 的默认源
replace-with = 'ustc'

[source.ustc]
# 中科大镜像,使用 sparse 协议(Rust 1.68+ 支持,速度更快)
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"

使用清华源 ​

toml
# ~/.cargo/config.toml

[source.crates-io]
replace-with = 'tuna'

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

使用字节跳动源(rsproxy) ​

toml
# ~/.cargo/config.toml

[source.crates-io]
replace-with = 'rsproxy-sparse'

[source.rsproxy-sparse]
registry = "sparse+https://rsproxy.cn/crates.io-index/"

常用国内镜像源对比 ​

镜像源提供方Rustup 支持Cargo sparse 支持稳定性
mirrors.ustc.edu.cn中国科学技术大学支持支持高
mirrors.tuna.tsinghua.edu.cn清华大学支持支持高
rsproxy.cn字节跳动支持支持高
mirrors.aliyun.com阿里云部分支持支持中

三个主流镜像源(中科大、清华、rsproxy)选哪个都行,稳定性都不错。如果一个不通就换另一个试试。

完整配置示例 ​

下面是一套完整的配置方案,以中科大源为例,同时配置 Rustup 和 Cargo:

Windows PowerShell 永久配置:

powershell
# 第一步:设置 Rustup 镜像(永久生效)
[System.Environment]::SetEnvironmentVariable('RUSTUP_DIST_SERVER', 'https://mirrors.ustc.edu.cn/rust-static', 'User')
[System.Environment]::SetEnvironmentVariable('RUSTUP_UPDATE_ROOT', 'https://mirrors.ustc.edu.cn/rust-static/rustup', 'User')

然后创建或编辑 Cargo 配置文件:

powershell
# 第二步:创建 Cargo 配置文件(如果不存在的话)
# 文件路径:C:\Users\你的用户名\.cargo\config.toml
New-Item -ItemType File -Path "$env:USERPROFILE\.cargo\config.toml" -Force

在 config.toml 中写入:

toml
# C:\Users\你的用户名\.cargo\config.toml

[source.crates-io]
replace-with = 'ustc'

[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"
powershell
# 第三步:重新打开 PowerShell,验证配置
# 创建一个测试项目来检验 crate 下载速度
cargo new mirror-test
cd mirror-test

# 添加一个依赖,观察下载速度
cargo add serde
cargo build

基本示例 ​

从零开始在全新 Windows 系统上配置镜像并安装 Rust:

powershell
# 第一步:设置 Rustup 镜像环境变量
$ENV:RUSTUP_DIST_SERVER = 'https://mirrors.ustc.edu.cn/rust-static'
$ENV:RUSTUP_UPDATE_ROOT = 'https://mirrors.ustc.edu.cn/rust-static/rustup'

# 第二步:下载并运行 rustup-init.exe(从 https://rustup.rs/)
# 安装过程中的下载会走镜像源,速度快很多

# 第三步:安装完成后,配置 Cargo 源
# 创建 ~/.cargo/config.toml 文件,写入以下内容:
toml
[source.crates-io]
replace-with = 'ustc'

[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"
powershell
# 第四步:验证
cargo new hello
cd hello
cargo add rand
cargo build
# 如果依赖下载很快(几秒内完成),说明镜像配置成功

常见问题 ​

问题一:配置了镜像还是很慢怎么办?

先检查环境变量是否生效:echo $ENV:RUSTUP_DIST_SERVER(PowerShell)。如果输出为空,说明环境变量没有正确设置。另外确认 config.toml 文件的路径是否正确——是 ~/.cargo/config.toml,不是项目目录下的。

问题二:config 和 config.toml 哪个对?

两个都行。Cargo 同时支持 ~/.cargo/config 和 ~/.cargo/config.toml。推荐用带 .toml 后缀的,因为编辑器能正确识别文件格式并提供语法高亮。如果两个文件都存在,.toml 版本优先。

问题三:sparse 协议是什么?和 git 协议有什么区别?

协议写法首次下载速度增量更新速度Rust 版本要求
gitregistry = "https://..."慢(需要克隆完整索引仓库)中等所有版本
sparseregistry = "sparse+https://..."快(只下载需要的索引)快1.68+

如果你的 Rust 版本是 1.68 或更新的(基本上 2023 年之后安装的都是),强烈建议用 sparse 协议,首次下载速度差距尤其大。

问题四:公司内网环境怎么配置?

如果公司有内部 Rust 镜像,让运维提供镜像地址,用同样的方式配置即可。如果没有内部镜像,可以配置 HTTP 代理:

toml
# ~/.cargo/config.toml

[http]
proxy = "http://你的代理地址:端口"

[https]
proxy = "http://你的代理地址:端口"

适用场景 ​

  • 国内开发环境:几乎所有在中国大陆进行 Rust 开发的场景都需要配置镜像
  • CI/CD 流水线:构建服务器如果在国内,配置镜像能显著缩短构建时间
  • 教学和培训环境:避免学员因为网络问题卡在依赖下载步骤上
  • 离线或弱网环境:配合 cargo vendor 命令可以把依赖打包到本地,完全离线编译

注意事项 ​

  • Rustup 的镜像和 Cargo 的镜像是两套独立的配置,需要分别设置
  • ~/.cargo/config.toml 是全局配置,会影响所有 Rust 项目;如果只想给某个项目配置,可以把 config.toml 放在项目根目录的 .cargo/ 文件夹下
  • 镜像源有时会短暂不可用或同步延迟,如果突然无法下载,等一会儿或换个镜像源试试
  • 切换镜像源后,已有项目的 Cargo.lock 文件中记录的下载源信息不会自动更新,但不影响正常使用
  • 不要同时配置多个 replace-with,只保留一个有效的源替换配置
  • 企业环境中使用镜像源时注意合规性,确认镜像源的内容和官方一致

总结 ​

国内使用 Rust 几乎必须配置镜像源,否则安装和依赖下载会非常痛苦。配置分两部分:Rustup 的镜像通过设置 RUSTUP_DIST_SERVER 和 RUSTUP_UPDATE_ROOT 环境变量实现,Cargo 的镜像通过编辑 ~/.cargo/config.toml 文件设置 replace-with 实现。推荐使用中科大、清华或 rsproxy 三个镜像源中的任意一个,它们都支持 sparse 协议,稳定性好。配置一次之后基本就不用再管了,但如果遇到某个镜像临时不可用的情况,知道怎么切换到另一个镜像就行。