入门 The Cargo Team 2026-09-13 15:48:21 · 0 阅读

第12章 Cargo 主目录

“Cargo home”充当下载与源码的缓存目录。在构建 crate 时，Cargo 会将已下载的构建依赖项存入此目录。你可以通过设置 CARGO_HOME 这个环境变量来更改其位置。若需在 Rust crate 内部获取该路径，可引用 home 库提供的 API。默认情况下，Cargo home 位于 $HOME/.cargo/。

请注意，Cargo home 的内部结构尚未保持稳定，随时可能发生变更。

Cargo home 由以下组件组成：

文件：

config.toml Cargo 的全局配置文件，详见参考手册中的 config 条目。
credentials.toml 由 cargo login 生成的私有登录凭证，用于登录 registry。
.crates.toml、.crates2.json 这些隐藏文件存储了通过 cargo install 安装的 package 信息。切勿手动编辑！

bin 该目录存放通过 cargo install 或 rustup 安装的 crate 可执行文件。需将该目录路径添加至 $PATH 环境变量，才能访问这些二进制文件。
git Git 源代码存储于此：
- git/db 若 crate 依赖于 Git 仓库，Cargo 会将其以裸仓库（bare repo）形式克隆至此目录，并根据需要更新。
- git/checkouts 当使用 Git 源时，系统会从 git/db 中的裸仓库检出指定 commit，并将其文件提取至此目录。这确保了编译器能获取该依赖项指定 commit 中的实际文件。支持对同一仓库的不同 commit 进行多次检出。
registry 存放 crate 注册表（如 crates.io）的包和元数据。
- registry/index 索引是一个裸 Git 仓库，包含注册表中所有可用 crate 的元数据（版本、依赖项等）。
- registry/cache 下载的依赖项存储在此缓存中。crate 是压缩后的 gzip 归档文件，扩展名为 .crate。
- registry/src 如果某个包需要已下载的 .crate 归档文件，它会被解压到 registry/src 目录，以便 rustc 找到其中的 .rs 文件。

在 CI 中缓存 Cargo 主目录

为了避免在持续集成过程中重新下载所有 crate 依赖项，你可以缓存 $CARGO_HOME 目录。然而，缓存整个目录通常效率较低，因为其中会包含两份下载的源码。例如，如果我们依赖 serde 1.0.92 并缓存了整个 $CARGO_HOME，实际上会将源码缓存了两次：registry/cache 中的 serde-1.0.92.crate 文件，以及 registry/src 中 serde 的解压后 .rs 文件。这可能会不必要地拖慢构建速度，因为下载、解压、重新压缩以及将缓存上传回 CI 服务器都需要耗费时间。

如果你希望缓存通过 cargo install 安装的二进制文件，则需要缓存 bin/ 文件夹以及 .crates.toml 和 .crates2.json 文件。

通常，跨构建缓存以下文件和目录就足够了：