working-with-mbx

使用 mbx

概述

mbx（Mr. Boxington）是 Cargo 的共享编译缓存，还会自动管理 target/ 目录。Cargo 仍负责解析依赖项并决定需要构建什么；mbx 会恢复匹配的编译结果，并为其他内容运行编译器。

在以下情况下使用此技能：

• 安装 mbx，或为普通 cargo 命令启用 mbx
• 构建报告的缓存命中很少，需要了解原因
• 判断 mbx 结果（命中／未命中／绕过）是否符合预期
• 从缓存存储区或托管的 target 目录中回收磁盘空间
• 为 CI 添加 mbx 缓存，或从 sccache／rust-cache 迁移

基本规则

1. 绝不要将 mbx 与 sccache 混用 —— 两者都会通过 RUSTC_WRAPPER 包装 rustc。如果 已设置 RUSTC_WRAPPER，mbx 会让位于它，构建将不会被缓存。
2. 通过 Cargo 的路径验证是否已启用，不要只依赖 mbx doctor —— doctor 无法 识别原生的 mise Rust 工具选项，因此，仅有设置警告并不意味着包装未启用。
3. 先诊断，再删除 —— 对构建运行 mbx explain。清除缓存 会销毁证据，而且下一次构建只会从头运行。
4. 使用两个全新的 target 目录衡量复用情况 —— 在同一个 target 中重新运行相同命令，衡量的是 Cargo 的新鲜度检查，而不是 mbx。

安装

使用 mise（推荐）

mise use --global --tool-option mr_boxington=true rust mr-boxington

需要 mise 2026.9.2 或更高版本。此操作会安装 Rust 和 mbx，并通过 mise 启用 Cargo 包装——无需运行 mbx setup。--tool-option 适用于后续工具，因此必须放在 rust 前面。移除 --global 可仅在当前项目中启用。

要与项目共享此配置，请在 mise.toml 中提交这两个工具：

[tools]
rust = { version = "stable", mr_boxington = true }
mr-boxington = "latest"

必须包含这两个条目。添加 mr_boxington = true 时，请保留项目现有的 Rust 版本。运行 mise install，然后进行构建。

不使用 mise

cargo install mbx --locked
mbx --version

Linux（x86-64／ARM64，glibc 和 musl）、macOS Apple Silicon 和 Windows（x86-64／ARM64）的发行压缩包可在 GitHub Releases 上获取，并附有 SHA256SUMS。参见 references/installation.md。

要让普通 cargo 使用独立安装的 mbx：

mbx setup
mbx setup --status

mbx setup 还会配置 rust-analyzer 的后台检查——原生的 mise 选项不会配置此项。可使用 --global 或 --local 指定作用范围；--yes 会接受推荐设置。

验证 mbx 是否确实在运行

这是最常见的故障：构建成功，但没有任何内容被缓存。

command -v cargo     # Unix
mbx doctor

在 Windows 上，使用 (Get-Command cargo).Path 或 where.exe cargo。

cargo 应解析为以下路径之一：

• mise 的命令包装器（例如 ~/.local/share/mise/command-wrappers/bin/cargo）
• mise shim
• mbx setup 安装的稳定版 mbx shim

直接调用 ~/.cargo/bin/cargo 会完全绕过 mise 集成。

非交互式环境（编码 Agent、SSH、桌面应用）

这些环境继承的 PATH 往往与交互式终端不同。可采用以下任一方式：

mise exec -- cargo build      # explicit, always works

或者将 mise 的 shims 目录加入该进程的 PATH。使用由应用本身运行的 command -v cargo 检查；更改环境后，重启应用。 在命令前加上 mbx 也始终有效：mbx build。

运行构建

mbx 会原样传递 Cargo 参数：

mbx build
mbx test --workspace --all-features
mbx clippy --workspace --all-targets -- -D warnings
mbx +stable check --workspace          # rustup-style toolchain selection

各次构建应使用相同的工具链、功能和配置文件，以复用相同的缓存工作。

查看结果

构建会输出类似以下内容的摘要：

mbx[cache]: 139 hits, 8 misses, 4 not looked up, 147 prefetched, 7 bypassed; 312.4 MiB downloaded, 0 B uploaded, 280.1 MiB stored locally

结果	发生情况
命中	mbx 恢复了匹配的编译结果
未命中	没有结果与键匹配；成功编译后会填充缓存
未查询	mbx 缺少可用的输入预测，因此必须先进行编译
已绕过	本次调用未使用共享缓存

计数反映 mbx 观察到的编译器操作。它们不包括 Cargo 因输出已是最新而跳过的工作——因此重新运行时可能显示零次命中。

mbx explain --last              # inspect the last recorded build, without running Cargo
mbx explain build --workspace   # run a build with diagnostics (preserves Cargo's exit status)
MBX_SUMMARY=full mbx build      # detailed breakdown
mbx tui                         # watch a build live, one row per compilation

衡量实际缓存复用情况

mbx build --target-dir target/cache-demo-first
mbx build --target-dir target/cache-demo-second

第二次构建可以恢复第一次构建记录的工作。使用尚未包含构建产物的目录名，并在之后将其删除——显式指定的目标目录不受管理。务必同时比较实际耗时；“节省的编译器时间”是各项操作的总和，并非节省的实际耗时。

命中率偏低时的排查方法

先运行 mbx explain build --workspace——它会按原因归类，并为每个类别提供指导。常见原因如下，大致按出现顺序排列：

• 缓存为空。 首次构建没有可用于推导键的 dep-info，因此“无法查找”可能占主导。
• 启用了增量构建。 设置 MBX_INCREMENTAL=1 后，工作区成员会进行增量编译，这些编译会绕过缓存，其上游 crate 也会未命中。
• 无法描述链接操作。 Linux、macOS 和 Windows 上的本机可执行文件、测试和过程宏都会缓存，但包含自定义或未建模输入的链接操作仍会执行。
• 输入不同。 不同检出目录使用的工具链、功能集、配置文件或 RUSTFLAGS 不同，会生成不同的键，并被报告为普通未命中。
• 构建脚本输出不同。 如果构建脚本将检出目录路径嵌入输出，就无法在不同检出目录之间复用。
• 构建使用了自己的 C 编译器。 设置 CC、HOST_CC、CXX 或 HOST_CXX 会使主机编译不受 mbx 管理。
• Rust 更新。 编译器是每个键的一部分，因此工具链升级会一次性使所有 rustc 操作失效。这是预期行为，并非错误。

如需查看每次编译的记录：MBX_BYPASS_LOG=bypass.log mbx build。

预期会绕过缓存的情况

compiler-query 和 standard-input 是常规编译器探测，不会产生可缓存的输出。简要汇总不会将它们计入绕过次数。无需处理这些情况。

其他常见症状

症状	首要检查项
普通 Cargo 未使用 mbx	command -v cargo；对于独立设置，还应检查 mbx setup --status
Cargo 等待目标锁	为并行构建指定不同的目标目录
构建前 Cargo 元数据失败	cargo metadata --no-deps --format-version 1
构建存储位于 NFS 上	将 cache_dir / target.root 移至本地存储（mbx 不支持 NFS）
远程请求失败	运行 mbx doctor，然后检查身份验证
存储空间超出预期	运行 mbx cache stats，然后运行 mbx gc --dry-run

单次命令绕过 mbx

MBX_DISABLE=1 cargo build

报告问题

mbx doctor --json
MBX_LOG=debug mbx build
MBX_BYPASS_LOG=bypass.log mbx build

这些信息包含绝对缓存路径、任何已配置的远程服务，以及你构建的 crate。不会打印凭据。

受管理的目标目录

默认情况下启用目标管理。对于没有现有 target/ 的检出目录，mbx 会将目标目录放在其缓存根目录下，并创建符号链接：

target -> <cache root>/targets/v1/<checkout digest>

在 Git 检出目录中，如有必要，mbx 会将链接路径添加到 .git/info/exclude，使 git status 保持干净，而无需修改项目的 .gitignore。

如果 --target-dir、CARGO_TARGET_DIR 或 Cargo 的 build.target-dir 指定了目标目录，mbx 不会对其进行处理。

无需删除现有目录内容，即可将其纳入管理：

mbx adopt                            # the current checkout
mbx adopt --recursive --dry-run ~/src  # preview

使用 MBX_TARGET_VIEWS=0 或 [target] views = false 禁用此放置方式。

磁盘管理

mbx cache stats     # action store, managed targets, learned incremental state
mbx cache dir       # where the store lives
mbx gc --dry-run    # preview collection under the configured budgets
mbx gc              # collect
mbx clean           # this workspace's managed target, link, and incremental state
mbx cache remove /path/to/workspace   # the above, plus forget its cache claims
mbx stats           # lifetime savings

构建后会自动进行清理，最多每小时一次。预算根据存储数据的磁盘容量调整：

预算	默认值	范围
gc.max_size（操作存储）	磁盘容量的 5%	5 GiB 至 500 GiB
target.max_size（受管理的目标目录）	磁盘容量的 10%	10 GiB 至 100 GiB
gc.incremental_max_size（已学习的增量状态）	磁盘容量的 5%	10 GiB 至 100 GiB

受管理的目标目录在闲置超过 target.max_age（30 天）后也会被清理；检出目录不存在时也会清理。缓存可以丢弃——始终可以重新构建。请注意，cargo clean 不会移除 mbx 的私有增量状态；mbx clean 会。

配置

按以下三个来源的顺序读取，采用首个找到的值：

1. 环境变量（MBX_*）
2. Cargo 工作区根目录下的 .mbx.toml —— 仅限构建策略和调度器设置
3. 平台配置目录中的 mbx/config.toml：
   • Linux：~/.config/mbx/config.toml
   • macOS：~/Library/Application Support/mbx/config.toml
   • Windows：%APPDATA%\mbx\config.toml

未知的 TOML 键会被拒绝，因此拼错设置名称会报错。机器路径、远程缓存配置、 凭据、目标目录位置和垃圾回收设置，不能写在仓库的 .mbx.toml 中。

通过限制整台机器共用的编译池，让笔记本保持响应；该编译池默认使用所有逻辑 CPU 和 85% 的物理内存：

[scheduler]
cpus = 4
memory = "8GiB"

各功能的关闭开关：

开关	关闭的功能
MBX_SCHEDULER=0	整台机器共用的编译调度
MBX_CC=0	构建脚本和 mbx exec 的 C/C++ 缓存
MBX_TARGET_VIEWS=0	托管的目标目录
MBX_CACHE_LINKS=0	原生链接缓存
MBX_LEARNED_INCREMENTAL=0	学习型增量复用
MBX_SAVINGS=off	节省情况行

CI

steps:
  - uses: actions/checkout@v7
  - uses: jdx/mr-boxington-action@v1
  - run: mbx test --workspace

请在操作之前安装工具链——生成的密钥涵盖操作系统、架构以及 PATH 中 rustc 的身份。推送到默认分支时会填充归档；拉取请求（包括来自复刻仓库的请求） 只会恢复缓存。设置了 CI 或 GITHUB_ACTIONS 时，mbx 会自动使用说明性 CI 摘要。

从 sccache 迁移时，需要移除它：从 RUSTC_WRAPPER、 ~/.cargo/config.toml 中的 build.rustc-wrapper 以及任何安装步骤中删除它，然后运行 mbx doctor。从 rust-cache 迁移则是替换该操作——在相同路径上同时运行两者会导致 重复的恢复和保存工作。

可用参考资料

• references/getting-started.md - 从安装到首次缓存构建
• references/setup.md - Cargo 包装、rust-analyzer、验证 Cargo 的路径
• references/troubleshooting.md - 症状表和诊断
• references/cache-results.md - 命中/未命中/绕过、衡量复用情况
• references/limits.md - mbx 会和不会缓存的具体内容
• references/managed-targets.md - 目标目录位置、接管、预算
• references/configuration.md - 完整的设置参考
• references/incremental.md - 学习型增量复用
• references/scheduling.md - 并行构建、整台机器共用的编译池
• references/github-action.md - CI 设置
• references/cookbook/migrate.md - 从 sccache 或 rust-cache 迁移
• references/cookbook/local-development.md - 编辑器、监视循环、调试
• references/remote-cache.md - 缓存服务和 S3 后端
• references/cli/ - 各命令的标志和参数

使用 ./update-docs.sh 刷新以上所有内容。

警示信号——你即将犯错

• 为了“以防万一”而保留 sccache 配置 → mbx 会静默地停止缓存
• “mbx doctor 对设置发出了警告，所以 mbx 没有生效” → 先检查 command -v cargo
• 在同一个目标目录中连续运行两次相同的构建来验证缓存是否有效 → 测量的是 Cargo 的新鲜度
• 为了修复较低的命中率而清除缓存 → 先运行 mbx explain --last
• 追查 compiler-query / standard-input 绕过项 → 这是常规探测，没有内容可缓存
• 告诉编码 Agent 或 CI 脚本调用 ~/.cargo/bin/cargo → 会绕过 mise 集成
• 将 [remote] 凭据写入已提交的 .mbx.toml → 会被拒绝；请使用环境变量
• 在监视循环中添加 cargo clean → 会丢弃 Cargo 的新鲜度信息