Vercel 部署错误指南：Invalid Region or DC Identifier 的成因与修复

• CLI
• 后端
• 云原生

本文围绕 Vercel 开源仓库（GitHub 加速计划 / ve / vercel）中的错误说明文档 errors/deploy-invalid-dc.md 展开，系统讲解在配置regions（区域）时出现 "Invalid Region or DC Identifier" 错误的根本原因、合法取值清单，以及通过vercel.json配置文件与 CLI--regions参数两种方式正确指定部署区域的方法。读完本文，你将能准确区分"区域标识（Region identifier）"与"数据中心标识（DC identifier）"两类取值，避免再次触发该部署错误。

错误现象：何时会触发该错误

在 Vercel 平台中，部署时可以显式指定 Serverless Function 需要运行的地域，从而将代码部署到靠近用户的数据中心（DC, Data Center），降低延迟。当你在以下任一位置提供了regions配置时：

• 项目根目录的vercel.json配置文件；
• CLI 部署命令的--regions命令行参数；

如果其中使用了未知或非法的 DC 标识符，部署请求就会失败，并返回本文档所描述的Invalid Region or DC Identifier错误。

简单来说，该错误的触发条件只有一个：regions中填写了平台不认识的字符串。因此修复思路也非常直接——核对取值是否属于平台维护的合法标识符集合，并确保字符串全部为小写。

合法的 Region 标识符（Region Identifiers）

错误说明文档中明确列出了当前合法的 Region 标识符：

这里有两个关键约束：

1. 大小写敏感：文档强调 "Regions and DCs have to be inlowercase"，即区域与数据中心标识符都必须使用小写。使用SFO、Iad等大小写混合形式同样会被判定为无效。
2. all的特殊性：all是一个专用通配值，语义是"扩展到全部数据中心"，因此它在regions列表中只能出现一次，不能与sfo、iad等具体区域混用或重复声明。

从 Region 到 DC：CLI 内部的标识符转换

在 Vercel CLI 中，用户提供的 Region 标识符并不会原样发送给平台 API。错误说明文档指出：

In Vercel CLI, they currently are transformed to DC identifiers before being sent to our APIs.

即CLI 会在请求发出前，把 Region 标识符转换为对应的 DC 标识符。这是理解该错误的关键：你配置时写的是 Region 标识符，但平台 API 校验的是 DC 标识符，两者之间存在一层隐式映射。

合法的 DC 标识符（DC Identifiers）

与上述 Region 一一对应的合法 DC 标识符为：

从源码证据看，仓库中大量使用 DC 标识符的形态。例如packages/build-utils/test/unit.get-lambda-options-from-function.test.ts中的测试用例直接以regions: ['sfo1', 'iad1']形式构造 Lambda 配置；packages/next/test/integration/vercel-json-regions/vercel.json中的集成测试样例同样使用"regions": ["iad1", "sfo1"]的 DC 标识符形态。这说明在配置解析与 API 交互的最终环节，sfo1、iad1这类 DC 标识符才是被真正接受的值。

也正因存在 Region → DC 的转换层，当你在vercel.json或 CLI 参数中误填了类似sfo2、iad9这类不存在的 DC 编号时，转换层无法完成映射，从而触发 "Invalid Region or DC Identifier"。

修复方式一：通过vercel.json配置 regions

最常用的修复方式是在项目根目录的vercel.json中声明合法区域。仓库集成测试 vercel-json-regions/vercel.json 给出了一个可直接参考的完整样例：

{ "version": 2, "builds": [ { "src": "package.json", "use": "@vercel/next" } ], "functions": { "app/api-route/route.js": { "regions": ["iad1", "sfo1"], "functionFailoverRegions": ["dub1", "hnd1"] } } }

几点实操要点：

• functions.<路径>.regions接受一个字符串数组，每一项必须是合法标识符（Region 或 DC 形态均可，CLI 会统一转换）。
• 同一函数可以部署到多个区域，数组中按需罗列多个值即可。
• 若希望函数扩展到全部数据中心，可使用"regions": ["all"]，但注意该值只能出现一次。
• 同文件中的functionFailoverRegions用于配置故障转移区域，其取值约束与regions一致。

修复方式二：通过 CLI--regions参数指定

除配置文件外，也可以在部署命令中通过--regions参数临时指定区域。错误说明文档给出的标准用法为：

vercel --regions sfo,bru,gru

这里有一个容易踩坑的格式要求：多个区域之间必须使用英文逗号（,）分隔，且逗号后不要误加空格（CLI 解析时会先做 trim，但为了可读性与兼容性，建议保持sfo,bru,gru的紧凑写法）。

从仓库源码可以印证--regions参数的解析逻辑。在 packages/cli/src/commands/deploy/command.ts 中，该参数被定义为字符串类型：

{ name: 'regions', shorthand: null, type: String, argument: 'REGION', deprecated: false, description: 'Set default regions to enable the deployment on', }

而在 packages/cli/src/commands/deploy/index.ts 中，参数值会经过拆分、去空白、过滤空项的处理，并且优先级高于vercel.json中的regions配置：

const regionFlag = (parsedArguments.flags['--regions'] || '') .split(',') .map((s: string) => s.trim()) .filter(Boolean); const regions = regionFlag.length > 0 ? regionFlag : localConfig.regions;

这段源码揭示了两个实用结论：

1. 命令行参数在内部就是按,切分成数组的，这与文档中"用逗号分隔"的要求完全对应；
2. 当--regions未提供时，CLI 会回退读取vercel.json（即localConfig）中的regions字段。因此，"配置文件配错导致报错"与"命令行参数配错导致报错"两条路径都可能触发该错误，排查时需要同时检查两处。

常见排查清单

遇到Invalid Region or DC Identifier时，按以下顺序逐项核对：

1. 检查大小写：所有标识符必须为小写（sfo而非SFO）。
2. 检查取值：确认每个值都落在合法清单内——Region 为all/sfo/bru/gru/iad，DC 为sfo1/bru1/gru1/iad1。
3. 检查all的使用：all只能出现一次，且不要与其他具体区域混填。
4. 检查 CLI 分隔符：多个--regions值必须用英文逗号分隔，例如vercel --regions sfo,bru,gru。
5. 检查来源：同时确认vercel.json与--regions命令行参数两处配置（命令行优先级更高），避免其中一处残留了旧的非法值。
6. 检查拼写：DC 编号后缀目前仅1（如sfo1），sfo2、iad9这类不存在的编号会直接导致校验失败。

结语

"Invalid Region or DC Identifier" 是 Vercel 部署流程中典型的配置校验类错误，成因集中在"大小写错误、取值非法、all误用、分隔符错误"四类情况。通过掌握 Region 标识符与 DC 标识符的两层取值清单，并理解 CLI 在请求前完成的 Region → DC 转换机制，即可快速定位并修复问题。配置时建议优先使用仓库测试样例中验证过的 DC 标识符形态（如iad1、sfo1），并与 errors/deploy-invalid-dc.md 文档中列出的合法清单保持一致，即可稳定通过部署校验。

• CLI
• 后端
• 云原生