适用条件与这次修订

适用于已有 Cargo 的 Windows、macOS、Linux 可信项目。本文按 2026-10-25 读取的 Cargo Book 核对；先用 cargo --version 记录实际版本，用 cargo fetch --help 确认参数。未执行真实依赖下载，也没有验证第三方镜像可用性。原文发布于 2026-03-26，本次实质修订配置说明和排查流程。

Cargo 负责项目依赖；遇到 Rustup 工具链下载错误应另查工具链下载路径。旧文把 registry.default 写为 sparse+https://… 的做法不正确：该字段是注册源名称，不是镜像地址。也不要把旧的 CARGO_REGISTRY_INDEX 示例当成现行通用设置；官方自定义注册源使用带注册源名的 CARGO_REGISTRIES_<NAME>_INDEX 形式。

第一步：从错误定位实际请求

报错附近的内容需要区分的链路应记录的信息
更新 crates.io 索引索引协议和域名是 sparse HTTPS 还是 Git 索引
下载某个 crate 失败包文件下载地址失败包名、版本和请求主机
failed to fetch…Git URLGit 依赖或 Git 索引获取协议、地址及认证错误
锁文件需要更新依赖解析与锁文件条件是否缺少或改动了 Cargo.lock

当前文档将 crates.io 的协议默认值列为 sparse；旧版本或项目覆写可能仍用 git。浏览器能打开 crates.io 首页不等于索引与包文件都能下载。先记录失败主机，不预设是节点或镜像故障。

第二步：用 fetch 检查下载，不先更新依赖版本

普通用户，在含 Cargo.toml 且已有有效 Cargo.lock 的项目根目录
cargo --version
cargo fetch --locked

fetch 会下载 Git 和注册源依赖并写入 Cargo 缓存；--locked 要求沿用现有锁文件，缺失锁文件或必须改变依赖解析时会报错。没有锁文件的项目应先按项目流程生成、审阅锁文件，再进行这组对照，不把该报错当网络失败。未指定 target 时可能下载多个目标的依赖，需预留流量和空间。

第三步：用一次命令的配置验证本地 HTTP 代理

先确认客户端的 HTTP 或 mixed 入口正在运行。把 PORT 换成实际端口；127.0.0.1 指 Cargo 运行的机器。以下写法面向 macOS/Linux 的 bash 或 zsh；Windows 可使用后面的临时 TOML 文件方案，避免不同终端传递嵌套引号的差异。

macOS / Linux：单次参数，不写全局配置；先替换 PORT
cargo --config 'http.proxy="http://127.0.0.1:PORT"' fetch --locked

Windows PowerShell 可在项目根目录新建一个不含凭据的 roxi-proxy-check.toml，先确认没有同名文件。填入下面的临时片段后执行命令；该文件只包含本次覆写项，不是完整 Cargo 配置的替代品。

roxi-proxy-check.toml；把 PORT 替换为本机实际 HTTP 代理端口
[http]
proxy = "http://127.0.0.1:PORT"
Windows PowerShell；在该临时文件所在目录运行
cargo --config .\roxi-proxy-check.toml fetch --locked

--config 优先于环境变量及通常配置文件。本次只覆写 http.proxy，原有离线开关、注册源替换和其他设置仍可能影响结果。预期原失败请求能够继续；若仍失败，记录主机与错误是否变化，不连续增大重试次数。

第四步：只在 Git 链路失败时考虑外部 Git

Cargo 内建 Git/SSH 支持和命令行 Git 不完全相同，例如内建 SSH 不使用 OpenSSH 的 config 文件。仅在依赖是 Git、且现有受信任 Git 工具已按项目要求配置好时，才考虑下面的单次对照。它不会修复普通 crate 包文件的下载，也不把 Git 凭据变成 HTTP 代理凭据。

各桌面平台；需要已有 Git，仍保护锁文件
cargo --config net.git-fetch-with-cli=true fetch --locked

若切换后成功，应核对实际使用的 Git 配置与网络路径，再决定是否保留；不要复制账号凭据到项目。私有仓库认证问题按官方 Git 认证文档处理，公共依赖突然要求认证时先核对 URL。

第五步：验证与恢复

成功取得依赖后，在相同目录及锁文件条件下验证缓存
cargo fetch --locked --offline

离线通过表示当前依赖已可从本地取得，不能证明网络仍然畅通，也不能保证构建脚本不再访问网络。网络验收要回看在线 fetch 是否实际请求了原失败目标；如果原本全命中缓存，就如实记录本轮没有验证下载。

  1. 撤下单次 --config 参数；临时 TOML 文件确认只含本次内容后删除，不提交到仓库。若还改了持久配置，恢复备份。
  2. 保持 Cargo.lock 不变，重跑原失败操作。证书或权限错误继续按原错误处理，不关掉 TLS 校验。
  3. 需要镜像时另行核对项目批准的完整 source replacement 方案；本稿不提供未经验证的镜像地址，也不通过 cargo update 改动依赖来掩盖联网问题。