mr-boxington 配置完全手册:settings 命令、环境变量与优先级规则速查清单
mr-boxington 配置完全手册:settings 命令、环境变量与优先级规则速查清单
mr-boxington(命令行工具为 mbx)是一个面向 Rust 项目的构建缓存工具:它跨 worktree 复用 Cargo 编译结果、自动清理 target/ 并协调并行构建。本文用一份速查清单带你掌握 mbx 配置的三大件——mbx settings 命令、MBX_* 环境变量与配置优先级规则,看完即可独立完成日常调参。官方配置参考见 docs/configuration.md。
一、配置从哪里读取?优先级规则一次讲清
mbx 默认值开箱即用,不需要任何配置文件。当你想修改行为时,配置从三个位置读取,先找到的值生效(优先级从高到低):
| 优先级 | 来源 | 说明 |
|---|---|---|
| 1 | 环境变量 MBX_* |
最高优先级,可临时覆盖一切文件配置 |
| 2 | 工作区根目录的 .mbx.toml |
仅接受 工作区策略 中的设置 |
| 3 | 全局配置 mbx/config.toml |
平台配置目录下的用户级配置 |
| 4 | 内置默认值 | 前三者都未设置时生效 |
全局配置文件路径:
- Linux:
~/.config/mbx/config.toml(遵循$XDG_CONFIG_HOME) - macOS:
~/Library/Application Support/mbx/config.toml - Windows:
%APPDATA%\mbx\config.toml
两个重要细节:
- 拼错即报错:mbx 会拒绝未知的 TOML 键,一个写错的设置名会直接成为错误(可用
mbx settings unset清除它); - 大小写敏感的单位值:
20GB与20GiB是两个不同的值。
二、mbx settings 命令速查:set / get / ls / unset
mbx settings 是读写全局配置文件的子命令组,无需手改文件。四个子命令一览:
| 命令 | 用法 | 作用 |
|---|---|---|
| 写入设置 | mbx settings set <KEY> <VALUE> |
写入全局配置文件,文件不存在会自动创建 |
| 读取单个设置 | mbx settings get <KEY> |
打印当前生效值(环境变量 > 全局文件 > 默认值) |
| 列出设置 | mbx settings ls [KEY] |
列出全部设置;给 gc 这类组名则只列该组 |
| 移除设置 | mbx settings unset <KEY> |
删除键使其回退默认值 |
常用示例:
mbx settings set gc.max_size 20GiB # 限制动作存储到 20GiB
mbx settings set target.evict_first .claude/worktrees,tmp
mbx settings get gc.max_size # 查看当前值
mbx settings ls gc # 列出 gc 组的所有设置
mbx settings unset gc.max_size # 恢复默认
使用 set 时值得知道的规则:
- 值必须通过类型与取值校验,校验不通过就不会写入任何内容;
- 列表类设置用逗号分隔,如
mbx settings set target.keep ~/src,/work; - 文件中的注释、排版与其他设置会被完整保留,符号链接文件保持符号链接;
- 表结构设置(如
linker.profiles)需要直接编辑配置文件; - 仅环境变量的设置(如
MBX_VERIFY)不能用set写入; ls不打印remote.token的值,但mbx settings get remote.token可以。
四个子命令的完整文档分别在 docs/cli/settings/set.md、docs/cli/settings/get.md、docs/cli/settings/ls.md、docs/cli/settings/unset.md。
三、环境变量速查清单(MBX_*)
环境变量优先级最高,适合"只对这一次命令生效"的临时调整(POSIX 写法 NAME=value command;PowerShell 则先 $env:NAME 再执行,用完删除)。高频变量:
| 环境变量 | 对应设置 | 用途 |
|---|---|---|
MBX_CACHE_DIR |
cache_dir |
缓存目录,默认平台缓存目录下的 mbx(如 ~/.cache/mbx) |
MBX_VERIFY |
verify |
仅环境变量可用:同时编译并查缓存,比对输出做校验 |
MBX_SUMMARY |
summary |
构建摘要风格:auto/short/ci/full/off |
MBX_SAVINGS |
savings |
节省提示行风格:quips/plain/off |
MBX_SCHEDULER_RESERVE_CPUS |
scheduler.reserve_cpus |
从 CPU 预算中预留核心数给编辑器等前台工作 |
MBX_GC_MAX_SIZE |
gc.max_size |
动作存储(action store)的大小预算 |
MBX_GC_MAX_TOTAL_SIZE |
gc.max_total_size |
缓存构建数据的单一总预算 |
MBX_CC |
cc |
缓存 build script 与 mbx exec 中的 C/C++ 编译(默认开) |
MBX_DISPLAY |
display |
plain 关闭动画化的构建输出 |
MBX_REMOTE_URL |
remote.url |
远程缓存地址:https:// 缓存服务器或 s3://bucket/prefix |
完整的环境变量-设置对照(约 70 项)由设置声明生成,见 docs/cli/configuration.md,其声明源码在 crates/mbx/src/config.rs。
四、尺寸与时长怎么写
- 尺寸:同时支持 SI 与 IEC 单位,
20GB≠20GiB; - 时长:
30s、15m、1h、30d这类写法; - 部分大小/时长设置为
"none"表示禁用该限制(如gc.rustc_max_age)。
五、工作区策略:.mbx.toml 能写什么
仓库可检入一份 .mbx.toml,但只接受与机器无关的设置:
incremental、eager_incremental、share_out_dir、share_workspace_root、build_script_execution、cclinker.default与linker.profiles(path:选择器除外)scheduler.enabled/cpus/reserve_cpus/memory/priority/pressure/tests
不接受机器路径、远程缓存、凭据、诊断、target 放置与回收设置;出现不支持或拼错的键会直接报错。环境变量仍优先于 .mbx.toml。
六、常见配置配方
| 需求 | 命令 |
|---|---|
| 给编辑器留出 2 个核心 | mbx settings set scheduler.reserve_cpus 2 |
| 一份预算管住全部缓存数据 | mbx settings set gc.max_total_size 50GiB |
| 动作存储限制 20GiB | mbx settings set gc.max_size 20GiB |
| 清掉不再使用的 Rust 版本缓存 | mbx settings set gc.rustc_max_age 90d |
| 延长活跃 target 保留期 | mbx settings set target.max_age 60d |
| 让提示行更平实 | mbx settings set savings plain |
| 打印更详细缓存信息 | mbx settings set summary full |
| 首次编译即保留私有增量状态 | mbx settings set eager_incremental true |
其中 gc.max_total_size 是"单一缓存预算":动作存储、托管 target、学到的增量状态与生成源码树共用一个尺寸目标(如 50GiB),替代按磁盘规模计算的默认上限;用 mbx gc --dry-run 可预演回收。
全局配置文件示例(按需取用,非推荐配置):
# ~/.config/mbx/config.toml
cache_dir = "/var/cache/mbx"
incremental = false
summary = "auto"
savings = "quips"
[gc]
auto = true
max_size = "20GiB"
max_total_size = "50GiB"
min_free_size = "20GiB"
interval = "1h"
[target]
max_size = "30GiB"
max_age = "30d"
keep = ["~/src/app"]
[scheduler]
enabled = true
cpus = 16
reserve_cpus = 2
memory = "24GiB"
七、验证配置是否生效
配置改完不必靠猜,用这几条命令自查:
mbx doctor # 检查工具链、setup 与缓存访问
mbx settings ls # 列出全部设置的当前生效值
mbx gc --dry-run # 预演缓存回收
mbx tui # 实时观察构建与缓存状态
mbx tui 的仪表盘可以直观看到缓存活动、洞察与存储占用,是验证调参效果的好帮手:
结语
记住三条主线即可驾驭 mbx 配置:改全局用 mbx settings set,临时覆盖用 MBX_* 环境变量,仓库级共识写 .mbx.toml(且只能写工作区策略)。更多细节可查阅 docs/cli/index.md 中的命令总览与 docs/configuration.md 中的完整设置参考。


