国内镜像源配置
为什么需要镜像源
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 窗口有效)
$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 才生效)
[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)
# 在 ~/.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。
使用中科大源(推荐)
# ~/.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/"使用清华源
# ~/.cargo/config.toml
[source.crates-io]
replace-with = 'tuna'
[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"使用字节跳动源(rsproxy)
# ~/.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 永久配置:
# 第一步:设置 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 配置文件:
# 第二步:创建 Cargo 配置文件(如果不存在的话)
# 文件路径:C:\Users\你的用户名\.cargo\config.toml
New-Item -ItemType File -Path "$env:USERPROFILE\.cargo\config.toml" -Force在 config.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,验证配置
# 创建一个测试项目来检验 crate 下载速度
cargo new mirror-test
cd mirror-test
# 添加一个依赖,观察下载速度
cargo add serde
cargo build基本示例
从零开始在全新 Windows 系统上配置镜像并安装 Rust:
# 第一步:设置 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 文件,写入以下内容:[source.crates-io]
replace-with = 'ustc'
[source.ustc]
registry = "sparse+https://mirrors.ustc.edu.cn/crates.io-index/"# 第四步:验证
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 版本要求 |
|---|---|---|---|---|
| git | registry = "https://..." | 慢(需要克隆完整索引仓库) | 中等 | 所有版本 |
| sparse | registry = "sparse+https://..." | 快(只下载需要的索引) | 快 | 1.68+ |
如果你的 Rust 版本是 1.68 或更新的(基本上 2023 年之后安装的都是),强烈建议用 sparse 协议,首次下载速度差距尤其大。
问题四:公司内网环境怎么配置?
如果公司有内部 Rust 镜像,让运维提供镜像地址,用同样的方式配置即可。如果没有内部镜像,可以配置 HTTP 代理:
# ~/.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 协议,稳定性好。配置一次之后基本就不用再管了,但如果遇到某个镜像临时不可用的情况,知道怎么切换到另一个镜像就行。