将 YAML 转换为 TOML：何时以及如何进行切换

为什么将 YAML 转换为 TOML？

当团队希望使用一种更不容易出错的配置格式时，他们会从 YAML 迁移到 TOML。YAML 的显著空格和令人惊讶的类型强制转换（no 变成 false，1.10 变成数字）会导致实际错误。TOML 显式的、用方括号分隔的表消除了缩进歧义。这种转换在采用 Rust 工具链或简单地将多语言仓库统一为一种配置风格时很常见。

映射和序列如何转换

YAML 映射变成 TOML 表；YAML 序列变成 TOML 数组。方向与我们之前看到的 TOML→YAML 相反：

title: My App
database:
  host: localhost
  port: 5432

title = "My App"

[database]
host = "localhost"
port = 5432

YAML 的映射列表变成表数组：

steps:
  - name: build
    run: make
  - name: test
    run: make test

[[steps]]
name = "build"
run = "make"

[[steps]]
name = "test"
run = "make test"

哪些特性在 TOML 中没有对应项

这个方向上的转换可能会丢失信息，因为 YAML 具有 TOML 完全缺乏的特性：

• 锚点和别名（&anchor / *alias）——TOML 没有引用机制。转换器必须展开它们，将引用的数据内联复制。结果正确但更大，并且去重意图丢失。
• null——YAML 的 null（或空值）在 TOML 中没有类型。这些键通常会被丢弃；请决定这是否可以接受。
• 非字符串键——YAML 允许数字甚至序列作为映射键。TOML 键是字符串，因此此类键必须字符串化。
• 多个文档——单个 YAML 文件可以包含由 --- 分隔的多个文档。TOML 没有这样的概念；一次转换一个文档。

多行字符串

两种格式都支持多行字符串，但语法不同。YAML 块标量（| 字面量和 > 折叠）映射到 TOML 的三引号字符串：

description: |
  Line one
  Line two

description = """
Line one
Line two
"""

折叠的 > 标量（用空格连接行）在写入之前会转换为其已折叠的单行形式。

安全转换工作流程

1. 在脑海中解析或移除锚点/别名——知道它们会被展开。
2. 一次转换一个 YAML 文档。
3. 检查是否有重要的 null 键被静默丢弃。
4. 在提交之前使用解析器验证 TOML。

常见问题

YAML 转 TOML 会丢失数据吗？ 可能会。锚点/别名会被展开（丢失引用），空值会被丢弃，多文档文件必须拆分。普通的映射、序列和标量可以干净地转换。

YAML 锚点和别名会怎样？ TOML 没有引用，因此转换器会在使用引用的每个地方内联引用内容。数据被保留但重复。

我可以转换多文档 YAML 文件吗？ 不能一次完成——TOML 没有文档分隔符。将每个 --- 部分转换为单独的 TOML 文件。

将你的 YAML 粘贴到上面的转换器中，即可获得有效的 TOML，锚点已展开，表已自动生成。