Rust 缓存 Action

一个 GitHub Action，为 rust/cargo 项目实现智能缓存，具有合理的默认设置。

使用示例

- uses: actions/checkout@v4

# 在插件之前选择工具链（通过 action 或手动 `rustup` 调用），因为缓存使用当前 rustc 版本作为缓存键
- run: rustup toolchain install stable --profile minimal

- uses: Swatinem/rust-cache@v2
  with:
    # 缓存键前缀，可以更改以手动启动新的缓存
    # 默认值："v0-rust"
    prefix-key: ""

    # 用于替代自动基于 `job` 的键的缓存键，在多个作业中保持稳定
    # 默认值：空
    shared-key: ""

    # 一个额外的缓存键，与自动基于 `job` 的缓存键一起添加，可用于进一步区分作业
    # 默认值：空
    key: ""

    # 以空格分隔的环境变量*前缀*列表，其值contributes to环境缓存键
    # 环境变量通过*前缀*匹配，因此默认的 `RUST` 变量将匹配所有 `RUSTC`、`RUSTUP_*`、`RUSTFLAGS`、`RUSTDOC_*` 等
    # 默认值："CARGO CC CFLAGS CXX CMAKE RUST"
    env-vars: ""

    # cargo 工作空间和目标目录配置
    # 这些条目由换行符分隔，格式为 `$workspace -> $target`
    # `$target` 部分被视为相对于 `$workspace` 的目录，如果未明确给出，则默认为 "target"
    # 默认值：". -> target"
    workspaces: ""

    # 要缓存的额外非工作空间目录，由换行符分隔
    cache-directories: ""

    # 确定是否缓存工作空间的 `target` 目录
    # 如果为 `false`，则只缓存 cargo registry
    # 默认值："true"
    cache-targets: ""

    # 确定工作流失败时是否仍应保存缓存
    # 默认值："false"
    cache-on-failure: ""

    # 确定缓存哪些 crate
    # 如果为 `true`，则缓存所有 crate，否则只缓存依赖的 crate
    # 当 CI 工具使用额外的 crate 时很有用
    # 默认值："false"
    cache-all-crates: ""

    # 确定是否应保存缓存
    # 如果为 `false`，则只恢复缓存
    # 对于矩阵是累加的作业（例如额外的 Cargo 功能）或只希望保存来自 `master` 的运行到缓存时很有用
    # 默认值："true"
    save-if: ""
    # 要只缓存来自 `master` 的运行：
    save-if: ${{ github.ref == 'refs/heads/master' }}

    # 指定用作提供缓存的后端
    # 可以设置为 "github" 或 "buildjet"
    # 默认值："github"
    cache-provider: ""

更多示例可在 .github/workflows 目录中找到。

输出

cache-hit

这是一个布尔标志，当有精确的缓存命中时，将设置为 true。

缓存效果

此 action 仅缓存 crate 的依赖项，因此如果依赖项与自身代码的比率较高，效果会更好。

对于有 Cargo.lock 文件的仓库，它也最有效。只有 Cargo.toml 文件的库仓库效果有限，因为 cargo 会始终使用最新的依赖版本，这些版本可能未被缓存。

使用 Stable Rust 最有效，因为缓存与 Rust 版本相关联。使用 Nightly Rust 效果较差，因为它每天都会丢弃缓存，除非固定使用特定的 nightly 构建。

缓存详情

此 action 目前缓存以下文件/目录：

• ~/.cargo（已安装的二进制文件、cargo registry、缓存和 git 依赖）
• ./target（依赖项的构建产物）

此缓存自动由以下内容键控：

• github job_id
• rustc 发布版本 / 主机 / 哈希值
• 一些编译器特定环境变量的值（例如 RUSTFLAGS 等）
• 仓库中所有 Cargo.lock / Cargo.toml 文件的哈希值（如果存在）
• 仓库根目录中所有 rust-toolchain / rust-toolchain.toml 文件的哈希值（如果存在）
• 仓库根目录中所有 .cargo/config.toml 文件的哈希值（如果存在）

如果内置键不够用，可以提供额外的 key 输入。

在持久化之前，缓存会清理：

• ~/.cargo/bin 中在 action 运行前就存在的任何文件（例如 rustc）
• 不再使用的依赖项
• 任何非依赖项
• 增量构建产物
• 任何 mtime 超过一周的构建产物

特别是，不缓存工作空间 crate 本身，因为这样做通常不太有效。 出于这个原因，此 action 自动设置 CARGO_INCREMENTAL=0 以禁用增量编译，这样 Rust 编译器就不会浪费时间创建增量构建所需的额外产物。

不缓存 ~/.cargo/registry/src 目录，因为 Cargo 从 ~/.cargo/registry/cache 中的压缩 crate 存档重新创建它会更快。

该 action 也会尝试从之前的 Cargo.lock 版本恢复，因此 lockfile 更新应该只重新构建变更的依赖项。

该 action 调用 cargo metadata 来确定当前的依赖项集。

此外，该 action 自动解决了 cargo#8603 / actions/cache#403 问题，否则这些问题会导致 macOS 构建中的缓存损坏。

缓存限制和控制

这个专门的缓存 action 建立在 GitHub 维护的上游缓存 action 之上。同样的限制和约束也适用，详见此处文档： 缓存依赖项以加速工作流程

特别是，缓存目前总共限制为 10 GB，超过此限制将导致较旧的缓存被淘汰。

基础分支的缓存可用于 PR，但不能跨无关分支使用。

可以使用 Cache API 控制缓存，该 API 允许列出现有缓存并手动删除条目。

调试

该 action 会打印详细信息，说明它考虑了哪些信息作为缓存键，并输出更多仅用于调试的信息，说明在持久化缓存之前执行了哪些清理步骤。

你可以了解如何启用调试日志以查看这些详细信息以及与缓存操作相关的更多详细信息。

已知问题

• 缓存清理过程目前会删除 ~/.cargo/bin 中在 action 运行前就存在的所有文件（例如 rustc）。