macOS 上 Rust 开发环境与镜像

发表于 2026-04-19 更新于 2026-04-20 分类于 rust

在 macOS 上用 rustup 安装 Rust，并配置国内镜像以加速工具链与 crates 拉取。

前言

在 macOS 上做 Rust 开发，官方推荐通过 rustup 管理工具链与组件。
国内网络直接访问 static.rust-lang.org 与 crates.io 往往较慢或不稳定。
本文说明如何安装 rustup、为 rustup 与 cargo 配置镜像，并完成简单自检。
下文镜像地址以常见高校与社区镜像为例，若你所在环境有更合适的源，可按同样思路替换。

前提

编译本地依赖时，部分 crate 会调用系统链接器与 C 工具链。
若尚未安装 Xcode 命令行工具，可先执行安装命令并按提示完成。
安装完成后，clang 等工具可在终端中正常使用。

1	xcode-select --install

安装 rustup

安装脚本默认从官方域名拉取，可先临时设置 RUSTUP_DIST_SERVER 与 RUSTUP_UPDATE_ROOT，让 rustup 从镜像站获取静态资源与更新元数据。
下列变量在执行安装脚本之前导出，对首次安装与后续 rustup update 均生效。
以中科大镜像为例，在终端中执行下列命令。

1
2
3

export RUSTUP_DIST_SERVER="https://mirrors.ustc.edu.cn/rust-static"
export RUSTUP_UPDATE_ROOT="https://mirrors.ustc.edu.cn/rust-static/rustup"
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安装程序会询问安装类型，一般选择默认 stable 即可。
完成后按提示执行 source 或重新打开终端，使 PATH 包含 ~/.cargo/bin。

若你希望长期使用同一镜像，请把上述两行 export 写入 ~/.zprofile 或 ~/.bash_profile（视你使用的 shell 而定），避免每次手动设置。

Cargo 镜像

cargo 默认从 crates.io 拉取依赖索引与 crate 包。
可在 ~/.cargo/config.toml 中为 crates-io 指定替代源，以走国内镜像。
若文件不存在，可自行新建；下列示例使用稀疏索引（sparse+），与较新版本的 Cargo 默认行为一致。

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

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

部分团队会使用 rsproxy 等社区镜像，配置方式同样是 replace-with 指向镜像提供的 registry 地址。
若你使用的镜像站文档要求使用 git 协议形式的索引 URL，请以该文档为准，并与本机 Cargo 版本说明对照。

验证

确认 rustc 与 cargo 已可用，并查看版本号是否符合预期。

1 2	rustc -V cargo -V

新建一个临时项目并编译，确认依赖解析与构建流程正常。

1
2
3

cargo new /tmp/hello-rust --bin
cd /tmp/hello-rust
cargo build

若此处长时间卡在 Updating crates.io index，请检查 ~/.cargo/config.toml 是否保存正确、镜像是否可访问，以及环境变量是否在当前终端会话中生效。

小结

安装 Xcode 命令行工具，便于链接与构建原生依赖。
在安装与更新 rustup 前设置 RUSTUP_DIST_SERVER 与 RUSTUP_UPDATE_ROOT，并持久化到 shell 配置。
在 ~/.cargo/config.toml 中为 crates-io 配置替代源，加速索引与 crate 下载。
用 rustc -V、cargo new 与 cargo build 做快速验证。

镜像站域名与路径可能随维护公告调整。
若命令失败，请优先查阅对应镜像站的 Rust 或 crates 说明页并按最新指引更新。