mdBook 环境变量配置指南：用 MDBOOK_ 前缀覆盖 book.toml 中的任意配置

mdBook 的所有配置项都可以通过命令行环境变量在运行时覆盖，无需修改 book.toml 文件。本文系统讲解 MDBOOK_ 前缀环境变量的命名规则（大小写、单下划线、双下划线分隔）、JSON 值解析机制，并结合源码（config.rs）剖析其底层实现、顶层键白名单与 CI 脚本场景下的最佳实践。读完本文，你将能够在不触碰配置文件的前提下，以单行环境变量精确控制书名、作者、输出目录乃至任意渲染器与预处理器参数。

为什么需要环境变量覆盖机制

mdBook 的配置默认集中存放在书籍根目录的 book.toml 中（详见 general.md 的通用配置说明）。但在很多真实场景下，直接修改配置文件并不方便：

• CI/CD 流水线：不同分支、不同任务需要构建不同标题、不同输出目录的版本，修改并提交 book.toml 会让构建产物与源码状态耦合；
• 脚本批处理：同一份书稿需要批量产出多份定制版本，重复编辑配置文件低效且易出错；
• 临时实验：只想临时验证某个参数（如开启数学公式支持），不想留下改动痕迹。

mdBook 为此提供了环境变量覆盖通道：所有配置值都可以从命令行通过设置对应的环境变量来覆盖。该能力与 book.toml 本身处于同一优先级链路——先加载配置文件，再用环境变量进行覆盖，因此环境变量相当于“最后的覆盖层”。

命名规则：从 foo.bar.baz 到 MDBOOK_ 前缀

许多操作系统将环境变量的合法字符限制为字母、数字和下划线（_），因此点号（.）与连字符（-）都不能直接出现在环境变量名中。为了让 book.toml 中形如 foo.bar.baz 的层级键也能映射到环境变量，mdBook 设计了一套转换规则：

1. 变量必须以 MDBOOK_ 开头，该前缀标识“此变量用于 mdBook 配置”；
2. 去掉 MDBOOK_ 前缀后，将剩余字符串转换为 kebab-case（小写字母 + 连字符）；
3. 双下划线（__） 用于分隔嵌套层级，等价于配置键中的点号（.）；
4. 单下划线（_） 会被替换为连字符（-）。

官方文档给出的映射示例：

环境变量	转换后的配置键
MDBOOK_book	book
MDBOOK_BOOK	book（大小写不敏感）
MDBOOK_BOOK__TITLE	book.title
MDBOOK_BOOK__TEXT_DIRECTION	book.text-direction

注意 MDBOOK_BOOK__TEXT_DIRECTION 的转换过程：BOOK__TEXT_DIRECTION 小写化后为 book__text_direction，双下划线变为点号得到 book.text_direction，最后单下划线替换为连字符得到 book.text-direction——正好命中 general.md 中 [book] 表里 text-direction 这个 kebab-case 配置项。

因此，只需设置 MDBOOK_BOOK__TITLE 环境变量，就可以覆盖书的标题，完全不需要改动 book.toml：

export MDBOOK_BOOK__TITLE="My Awesome Book"
mdbook build

可覆盖的配置范围：不仅限于 book 元数据

环境变量覆盖并非只针对 <a href="https://link.gitcode.com/i/b2f8a10387144e5cca546a76b86e2edc" target="_blank">book] 表。mdBook 配置系统的顶层表包括 book、build、rust、output、preprocessor（对应 [config.rs 中的 Config 结构体字段），它们全部可以被环境变量定向覆盖。例如：

# 覆盖构建输出目录（对应 [build] build-dir）
export MDBOOK_BUILD__BUILD_DIR="dist"

# 覆盖 HTML 渲染器的智能标点开关（对应 [output.html] smart-punctuation）
export MDBOOK_OUTPUT__HTML__SMART_PUNCTUATION=false

# 覆盖 Rust playground 是否可编辑（对应 [output.html.playground] editable）
export MDBOOK_OUTPUT__HTML__PLAYGROUND__EDITABLE=true

# 覆盖自定义预处理器参数（对应 [preprocessor.xxx] 的任意键）
export MDBOOK_PREPROCESSOR__LINKS__SOME_FLAG=true

从源码结构看，环境变量键经过转换后最终进入 Config::set 方法，该方法逐一识别 book、build、rust、output、preprocessor 五个顶层表及其点号嵌套子键（见 config.rs），与 book.toml 的解析路径完全一致。

复杂值：环境变量值会先按 JSON 解析

普通配置项（如标题字符串、开关布尔值）直接用字符串赋值即可。但为了支持更复杂的配置结构，mdBook 规定：环境变量的值会先尝试按 JSON 解析，若解析失败则回退为普通字符串。

这意味着你可以用一段 JSON 一次性覆盖整个配置对象。官方文档给出的例子是在构建时完整覆盖书的所有元数据：

export MDBOOK_BOOK='{"title": "My Awesome Book", "authors": ["Michael-F-Bryan"]}'
mdbook build

上述命令等效于临时把 book.toml 中的 [book] 表替换为 title = "My Awesome Book"、authors = ["Michael-F-Bryan"]。同理，布尔值、数字、数组等 JSON 原生类型都能通过该机制注入：

# 布尔值
export MDBOOK_OUTPUT__HTML__PRINT__PAGE_BREAK=false

# 数组（对应 [output.html] additional-css）
export MDBOOK_OUTPUT__HTML__ADDITIONAL_CSS='["custom.css", "extra.css"]'

# 数字（对应 [output.html.search] limit-results）
export MDBOOK_OUTPUT__HTML__SEARCH__LIMIT_RESULTS=15

该“先 JSON 后字符串”的回退逻辑在源码中实现为 serde_json::from_str(&value).unwrap_or_else(|_| serde_json::Value::String(...))（见 config.rs）：任何能被 serde_json 解析的字符串都按 JSON 值处理，否则整体按字符串保存，再由 Config::set 转换成 TOML 值写入对应配置槽位。

CI 与脚本中的典型用法

文档特别强调，JSON 覆盖方式在 mdbook 被脚本或 CI 调用的场景下非常有用——有时在构建前根本无法（或不希望）更新 book.toml。常见的组合拳：

# .gitlab-ci.yml / GitHub Actions 片段示意
export MDBOOK_BOOK__TITLE="${CI_PROJECT_NAME} 文档"
export MDBOOK_BUILD__BUILD_DIR="public"
export MDBOOK_OUTPUT__HTML__SITE_URL="https://example.com/docs/"
mdbook build

或者配合 env 一次性注入：

env \
  MDBOOK_BOOK__TITLE="Release Notes v2.1" \
  MDBOOK_BUILD__BUILD_DIR="docs-output" \
  mdbook build

这样的写法让同一本书在不同流水线任务中产出不同标题、不同发布目录的版本，而源仓库中的 book.toml 始终保持干净。

源码实现原理

环境变量如何进入配置系统

在 mdBook 的命令驱动层，加载书籍的入口 MDBook::load 会先尝试从磁盘读取 book.toml（若不存在则使用 Config::default()），随后立即调用 config.update_from_env()? 合并环境变量覆盖（见 mdbook.rs）。也就是说，环境变量覆盖发生在“配置加载完成之后、书籍内容与渲染器/预处理器确定之前”，因此所有后续构建流程都能看到合并后的最终配置。

键名转换与顶层白名单

核心转换逻辑集中在 parse_env 函数（见 config.rs）：

fn parse_env(key: &str) -> Option<String> {
    key.strip_prefix("MDBOOK_")
        .map(|key| key.to_lowercase().replace("__", ".").replace('_', "-"))
}

它与本文第一节的命名规则完全对应：剥离前缀 → 全部小写 → 双下划线变点号 → 单下划线变连字符。仓库中的单元测试 parse_env_vars 直接验证了这一映射（见 config.rs），例如：

• MDBOOK_foo → foo
• MDBOOK_FOO__bar__baz → foo.bar.baz
• MDBOOK_FOO_bar__baz → foo-bar.baz

update_from_env 内部还通过正则 VALID_KEY（^(book|build|rust|output|preprocessor)($|\.)）对转换后的键做顶层白名单校验（见 config.rs）：只有落在五个顶层配置表之下的键才会被写入配置。像 MDBOOK_VERSION、MDBOOK_DOWNLOAD_URL 这类仅供用户脚本自行使用的变量会被安全忽略，不会干扰配置加载——这一行为在 0.5.1 版本更新中明确为“忽略非法的顶层环境变量配置键，允许诸如 MDBOOK_VERSION 的设置不再报错”（见 CHANGELOG.md）。

顶层表整体替换语义

需要注意一个版本差异：自 0.5.0 起，从环境变量设置的顶层配置值（如 MDBOOK_BOOK）会整体替换对应顶层表的内容，而不是与 book.toml 合并（见 CHANGELOG.md 的 0.5 迁移说明）。例如：

export MDBOOK_BOOK='{"title": "Only This Matters"}'

执行后 [book] 表只包含 title，book.toml 中同表下的 authors、language 等其余字段会被覆盖掉。因此：

• 想局部覆盖单个字段时，使用 MDBOOK_BOOK__TITLE 这类带双下划线的定向键；
• 想整体替换整个表时，才使用 MDBOOK_BOOK 这类顶层键配合 JSON 值。

同时 0.5.0 起，非法的环境变量键（如未知的顶层键 MDBOOK_FOO，或对象内部无效的键/值）会被显式拒绝并报错，而不再像旧版本那样静默忽略。

注意事项与边界情况

• 大小写不敏感：MDBOOK_book 与 MDBOOK_BOOK 等价，转换时统一小写化；
• 键名中的连字符由单下划线表示：book.text-direction 必须写作 MDBOOK_BOOK__TEXT_DIRECTION，而不是 MDBOOK_BOOK__TEXT_DIRECTION 之外的形式；若配置键本身含多个连字符（如 output.html.additional-css），则需写为 MDBOOK_OUTPUT__HTML__ADDITIONAL_CSS；
• 值解析失败自动回退字符串：MDBOOK_BOOK__TITLE="Hello World" 这类无法按 JSON 解析的值会原样作为字符串使用；
• 顶层表替换语义：覆盖整表时请确认其他字段的取舍，避免误伤 book.toml 中的既有配置；
• 相对路径基准不变：即使通过环境变量覆盖了 build.build-dir、output.html.theme 等路径类配置，路径依然以书籍根目录（book.toml 所在目录）为基准解析，与配置文件中的相对路径规则一致。

小结

MDBOOK_ 环境变量覆盖机制为 mdBook 提供了一条零文件改动的配置注入通道：命名上以“双下划线分隔层级、单下划线替代连字符、全小写 kebab-case”为约定，值上支持“先 JSON 后字符串”的弹性解析，范围上覆盖 book、build、rust、output、preprocessor 全部顶层配置表。其实现集中在 crates/mdbook-core/src/config.rs（update_from_env 与 parse_env），并在 crates/mdbook-driver/src/mdbook.rs 的加载流程中统一应用，配合单元测试 config.rs 可验证其行为。在 CI、脚本化构建与多环境发布场景下，它是与 general.md 中 book.toml 配置方案互补的强力工具。