Vercel 项目配置新增 vercel.toml 支持

Vercel 宣布其项目现在可以使用 vercel.toml 文件进行配置。这一变化为开发者提供了 vercel.json 之外的另一种配置选择，核心亮点在于引入了 TOML 格式的注释能力和更扁平的结构。

为什么 TOML 值得关注

TOML 是一种旨在明确表达语义的配置文件格式，与 JSON 相比，它允许写注释、结构更扁平，对人工阅读和版本维护更友好。Vercel 官方说明，vercel.toml 支持与 vercel.json 完全相同的配置属性，因此迁移成本并不高——开发者可以把现有 JSON 配置按 TOML 语法改写过来，同时获得注释能力。

对于长期被 vercel.json 中无法写注释所困扰的团队来说，这一点有实际价值。配置文件往往承载了部署逻辑、路由规则和团队约定，没有注释意味着上下文只能存在于文档或口口相传中。TOML 的引入让这些信息可以就近写在配置里。

TOML（Tom's Obvious Minimal Language）由 Tom Preston-Werner 于 2013 年提出，目前由社区维护并已发布 1.0.0 稳定规范。它的设计目标是把配置写成“显而易见”的形式：键值对语义明确、日期时间有原生类型、字符串无需转义即可跨行，并且原生支持注释。与 YAML 相比，TOML 不使用缩进表达层级，减少了因空白字符引发的歧义；与 JSON 相比，它允许注释且不要求大量引号与逗号。正因如此，TOML 被 Cargo（Rust）、pyproject.toml（Python 打包）、Hugo 等工具选为默认配置格式。其表（table）、内联表（inline table）与数组表（array of tables）三种结构，足以表达绝大多数部署配置所需的嵌套与重复条目。

项目配置文件只能三选一

Vercel 明确要求，每个项目只能使用一个配置文件：vercel.toml、vercel.json 或 vercel.ts。这意味着 vercel.toml 并不是叠加选项，而是替代选项。已有项目如果决定切换，需要移除其余配置文件，避免行为冲突。

这一约束也说明 Vercel 在配置层正在提供多种格式以适应不同偏好：JSON 胜在通用，TypeScript 胜在类型和逻辑能力，TOML 胜在可读性与注释。三者并存但不共存于同一项目，是这次更新最需要注意的边界。

以 Services 为例看实际写法

官方给出的示例展示了用 vercel.toml 配置 Services 的方式。示例中定义了一个 Next.js 前端服务和一个 FastAPI 后端服务，并配置了重写规则：

"$schema" = "https://openapi.vercel.sh/vercel.json"


示例中的 `$schema` 键指向一个 JSON Schema 地址，这是编辑器实现自动补全与校验的通用约定。Vercel 的 schema 以 vercel.json 为基准发布，因此 TOML 文件沿用了同一地址。需要注意，并非所有编辑器都能把 JSON Schema 直接映射到 TOML 文档上：VS Code 的 TOML 插件（如 Even Better TOML）支持通过 `#:schema` 注释指令关联 schema，而直接写 `"$schema"` 键在部分工具中可能只被当作普通配置项。因此在启用校验前，应先确认所用编辑器是否识别该写法，否则可能出现“配置正确但无提示”的情况。
# NextJS frontend
[services.frontend]
root = "frontend/"

# FastAPI backend
[services.backend]
root = "backend/"
entrypoint = "main:app"

[[rewrites]]
source = "/api/(.*)"
destination = { service = "backend" }

[[rewrites]]
source = "/(.*)"
destination = { service = "frontend" }

这段配置体现了 TOML 的两个特点。第一，注释直接写在服务定义上方，前端与后端的职责一目了然。第二，services.frontend、services.backend 这样的表结构把服务参数收拢在各自命名空间下，而 rewrites 使用数组表（[[rewrites]]）表达重复条目，整体层级比等价的 JSON 更扁平。

值得留意的是，示例中的 $schema 仍指向 vercel.json 的 schema 地址。这表达了配置属性与 JSON 版本一致的事实，但如果使用支持 schema 校验的编辑器，实际体验可能与预期有差异，需要以官方文档为准。

如何判断是否该切换

如果你的团队已经在 vercel.json 中维护了较多路由、重写或服务配置，并且经常需要向新成员解释这些配置的意图，vercel.toml 的注释能力会直接降低沟通成本。反过来，如果项目依赖 TypeScript 配置中的类型检查或动态逻辑，vercel.ts 仍然是更合适的选择，TOML 无法替代代码层能力。

对于新项目，选择哪一种格式更多取决于团队习惯。TOML 在可读性上的优势明显，但生态工具对 JSON 的支持通常更普遍。Vercel 同时保留三种格式，本质上是把选择权交给项目本身。

迁移时的注意事项

从 vercel.json 迁移到 vercel.toml 时，首先要确保删除旧配置文件，因为同一项目只允许一个配置入口。其次，JSON 中的嵌套对象在 TOML 中需要改写为表或内联表，数组结构需要改写为数组表，务必对照官方文档逐项验证。最后，只要配置属性本身没有被重命名，行为应保持一致，但建议在切换后检查部署日志中的路由与服务解析是否符合预期。

Vercel 在公告中只给出了 Services 这一种示例，其他配置项的 TOML 写法需要查阅文档确认。对于配置项较多的项目，建议先在测试项目中验证再迁移生产环境。

JSON 到 TOML 的改写有几条固定映射规则：JSON 对象在 TOML 中对应表（[section]）或内联表（{ key = value }）；JSON 数组若元素是同构对象，通常改写为数组表（[[items]]），若元素是标量则保留为普通数组；JSON 的 null 在 TOML 中没有对应值，需要省略该键或改用其他表达；布尔值、数字、字符串的写法基本一致，但 TOML 的字符串默认不转义反斜杠，含特殊字符时需使用字面量字符串（单引号）或基本字符串（双引号）加以区分。对于层数较深的配置，建议先用脚本或在线转换工具生成初稿，再人工校对键名与层级，避免数组表与普通表混用导致解析错误。