将 TOML 转换为 YAML 的最快方法是使用 yq -oy '.' file.toml。手动转换时，将 TOML 的 [table] 头映射为 YAML 的缩进块，将 TOML 数组映射为以短横线开头的列表，并且始终为有歧义的字符串加上引号，以避免“挪威问题”。
快速转换：使用 yq CLI
TOML（Tom’s Obvious, Minimal Language）在 2025 年 12 月发布了v1.1.0 版本，但 YAML 仍然是 CI/CD 流水线和 Kubernetes 清单的标准格式。yq 工具可以通过单条命令完成转换。
安装 yq
| 平台 | 命令 |
|---|---|
| macOS/Linux | brew install yq |
| Windows | choco install yq |
| Python（pip） | pip install yq |
推荐使用 Mike Farah 开发的 Go 语言版本以获得更快的速度。正如Mike Farah 的 yq 文档中所述，该工具会解码 TOML 结构并重新编码为整洁的 YAML。
执行转换
在终端中显示：
yq -oy '.' your-config.toml
保存到文件：
yq -oy '.' your-config.toml > your-config.yaml
-oy 标志将输出格式设置为 YAML，可处理键值对、嵌套表和数组。
语法对照表：TOML 结构到 YAML
开发者 Drew DeVault 曾指出，虽然 TOML 很流行，但 YAML 在处理深层嵌套时更为简洁。以下是精确的映射关系：
表映射为缩进键
TOML 使用方括号头；YAML 使用缩进。
| TOML | YAML |
|---|---|
[server] |
server: |
host = "127.0.0.1" |
host: 127.0.0.1 |
port = 8080 |
port: 8080 |
关键区别：在 TOML 中，缩进仅用于美观。而在 YAML 中，缩进是结构性的——哪怕一个空格错误都会导致整个配置文件失效。
数组映射为短横线列表
TOML： ports = [ 8000, 8001 ]
YAML：
ports:
- 8000
- 8001
正如 Knightli.com 所解释的，YAML 的“块样式”使列表更易读，前提是垂直对齐保持一致。
内联表和点分键
| TOML 构造 | YAML 等价形式 |
|---|---|
[a.b.c]（点分头） |
a: → b: → c:（嵌套缩进） |
point = { x = 1, y = 2 }（内联表） |
point: → x: 1 → y: 2 |
实际应用场景
Hugo 静态站点配置
Hugo 支持 hugo.toml、hugo.yaml 或 hugo.json。大多数项目最初使用 TOML（默认格式），当配置需要与 Netlify 或 GitHub Actions 等部署平台保持一致时，再迁移到 YAML。Hammer Europe 指出，hugo 命令会读取这些文件来决定如何将 Markdown 转换为线上站点。
Python 打包：pyproject.toml 到 CI/CD YAML
Python 社区通过 PEP 518 将 pyproject.toml 标准化。这些设置通常需要转换为 YAML 以用于 GitHub Actions CI/CD 工作流。对于 AI 智能体工作流，CocoIndex 报告称，优化的 YAML 配置可以将 token 用量减少高达 70%。
挪威问题及其他转换陷阱
NO 国家代码 Bug
在 YAML 1.1 中，像 NO、OFF 和 YES 这样的裸字符串会被自动强制转换为布尔值 false 或 true。TOML 通过要求所有字符串加引号来避免此问题。转换时，务必为 YAML 中有歧义的值加上引号：
| 值 | YAML 1.1 解释 | 修复方式 |
|---|---|---|
NO |
false |
"NO" |
OFF |
false |
"OFF" |
YES |
true |
"YES" |
On |
true |
"On" |
YAML 1.2（当前规范）修复了大部分强制转换问题，但许多解析器仍然默认使用 1.1 的行为。
缩进错误
YAML 解析器会拒绝缩进不一致的文件。常见错误包括：
- 混用制表符和空格（YAML 禁止使用制表符）
- 在一个块中使用 3 个空格，在另一个块中使用 2 个空格
- 列表项未对齐
AI 辅助生成
像 AgentBuilder 这样的工具允许你用自然语言描述配置并输出经过验证的 YAML。这种“描述 → 生成 → 验证”的循环有助于同时避免缩进错误和挪威问题。
总结
使用 yq -oy '.' file.toml 进行自动转换。手动操作时，将 TOML 表映射为 YAML 缩进，数组映射为短横线列表，并始终为可能被误认为布尔值的字符串加上引号。转换完成后，务必在部署前验证 YAML 输出——一个未对齐的空格或一个未加引号的 NO 就可能导致整个流水线崩溃。
常见问题
YAML 支持像 TOML 那样的注释吗？
支持。两者都使用 # 作为单行注释。YAML 注释可能会干扰多行字符串解析，因此在不确定时，请将注释放在单独的行上。
什么是 YAML 中的“挪威问题”？
在 YAML 1.1 中，像 NO（挪威的国家代码）这样的裸字符串会被自动转换为布尔值 false。TOML 通过要求所有字符串值加引号来避免此问题。将 TOML 转换为 YAML 时，请将任何可能有歧义的字符串用引号包裹。
哪种格式更适合处理深层嵌套？
YAML。TOML 需要为每个层级重复像 [table.subtable.subsubtable] 这样的长头部，这会变得冗长。YAML 用缩进来表示相同的层级结构——在深度嵌套时更加紧凑和易读。
