mr-boxington 配置完全手册:settings 命令、环境变量与优先级规则速查清单

原创2026-11-06 11:57:531,873 阅读

mr-boxington 配置完全手册:settings 命令、环境变量与优先级规则速查清单

mr-boxington(命令行工具为 mbx)是一个面向 Rust 项目的构建缓存工具:它跨 worktree 复用 Cargo 编译结果、自动清理 target/ 并协调并行构建。本文用一份速查清单带你掌握 mbx 配置的三大件——mbx settings 命令、MBX_* 环境变量与配置优先级规则,看完即可独立完成日常调参。官方配置参考见 docs/configuration.md。

mr-boxington 构建缓存输出界面:cargo-pretty 显示各 crate 的缓存命中与编译进度

一、配置从哪里读取?优先级规则一次讲清

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、cc
  • linker.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 tui 实时仪表盘:显示构建会话与缓存命中率

mbx tui 洞察页面:展示节省时间与缓存分布统计

结语

记住三条主线即可驾驭 mbx 配置:改全局用 mbx settings set,临时覆盖用 MBX_* 环境变量,仓库级共识写 .mbx.toml(且只能写工作区策略)。更多细节可查阅 docs/cli/index.md 中的命令总览与 docs/configuration.md 中的完整设置参考。

登录后查看全文
mr-boxington