@vercel/routing-utils 路由引擎演进全解:从 routes 规范化、服务路由委托到路径转换与缓存语义
@vercel/routing-utils 路由引擎演进全解:从 routes 规范化、服务路由委托到路径转换与缓存语义
本文以 packages/routing-utils/CHANGELOG.md 为主线,结合 @vercel/routing-utils 包内源码,系统梳理 Vercel 部署平台路由配置体系的核心组件:routes/rewrites/redirects/headers 的校验与规范化、service 服务路由委托、transforms 路径/头部转换、has/missing 条件匹配,以及 respectOriginCacheControl 缓存语义。读完本文,你将掌握该包的公开 API、JSON Schema 约束、底层规范化算法,以及 3.x → 6.x 各版本能力演进背后的实现原理。
一、包定位:Vercel 路由验证与规范化工具
@vercel/routing-utils 是 Vercel monorepo(packages/routing-utils)中负责路由配置校验与规范化的基础包,被 CLI、各框架 builder(Next.js、Remix 等)共同依赖。其 package.json 声明了两个关键依赖:path-to-regexp@6.1.0 与 path-to-regexp-updated(即 path-to-regexp@6.3.0 的别名安装),这为后续"双版本对比"机制埋下伏笔(见第七节)。
包的公开 API 集中在 src/index.ts 与 src/schemas.ts:
normalizeRoutes(inputRoutes):将用户输入的路由数组规范化为低层路由表,返回{ routes, error };getTransformedRoutes(vercelConfig):将vercel.json中的cleanUrls、trailingSlash、routes、redirects、headers、rewrites统一折叠成单一路由数组;routesSchema/rewritesSchema/redirectsSchema/headersSchema等 JSON Schema:用于 AJV 校验;mergeRoutes、appendRoutesToPhase:面向 builder 的多来源路由合并与相位插入;getOwnershipGuard、scopeRouteSourceToOwnership:服务路由的归属范围约束。
README 给出的两种典型用法如下:
import { normalizeRoutes } from '@vercel/routing-utils';
const { routes, error } = normalizeRoutes(inputRoutes);
if (error) {
console.log(error.code, error.message);
}
import { routesSchema } from '@vercel/routing-utils';
const ajv = new Ajv();
const validate = ajv.compile(routesSchema);
const valid = validate([{ src: '/about', dest: '/about.html' }]);
if (!valid) console.log(validate.errors);
二、routes 的去废弃:别名机制与配置共存(5.4.0 → 6.0.0)
历史上 routes 曾被弃用多年,官方建议改用 rewrites、redirects、headers、cleanUrls、trailingSlash 等高层配置。5.4.0 起(PR #15010)routes 被正式去废弃(undeprecate),并引入与高层字段一致的别名;6.0.0(PR #15020)则允许 routes 与上述字段共存,同时聚焦废弃 routes 内部的三个属性。
2.1 别名:src/source、dest/destination、status/statusCode
5.4.0 为 src、dest、status 分别增加别名 source、destination、statusCode,与 rewrites/redirects/headers 的 source/destination/statusCode 命名保持一致。规范化时字符串形式的别名会被折叠为规范字段并从路由对象上移除,见 src/index.ts 中 convertRouteAliases():
source→src;若同时定义src与source会抛错:cannot define both \src` and `source``;- 字符串形式的
destination→dest;dest与destination同时定义同样报错; statusCode→status;二者互斥。
注意一个例外:当 destination 是服务路由对象({ type: "service", service, path })时,它没有 dest 等价形式,会被原样保留(见第三节)。
2.2 共存与路由顺序(6.0.0)
6.0.0 的关键语义变更:routes 可以与 rewrites、headers、redirects、cleanUrls、trailingSlash 同时出现。合并后的路由顺序为:
cleanUrls → trailingSlash → routes → redirects → headers → rewrites
即 routes 插入在 cleanUrls/trailingSlash 之后、redirects/headers/rewrites 之前。这一顺序在 getTransformedRoutes()(src/index.ts)中得到印证:函数按 cleanUrls → trailingSlash → userRoutes → redirects → headers → rewrites 的顺序依次 normalizeRoutes 并 push 进结果数组,且 rewrites 之前固定插入 { handle: 'filesystem' } 相位标记。
2.3 废弃 handle、important、override(6.0.0)
6.0.0 同时废弃 routes 内部的 handle、important、override 三个属性。在 src/schemas.ts 的 routesSchema 中,handle 路由对象整体被标记 deprecated: true(仅保留 error、filesystem、hit、miss、resource、rewrite 六个枚举值),important 与 override 字段也均带 deprecated: true。在 src/types.ts 的类型定义中,handle、override、important 均标注 @deprecated。
三、服务路由(Service Routing):destination 对象委托(6.3.0 / 6.4.0)
服务路由是 6.x 的核心新增能力:让一条 route/rewrite 的 destination 指向某个命名服务(service),把请求委托给该服务内部的路由表处理。
3.1 服务目标格式(6.3.0)
6.3.0(PR 90a7cc1)引入服务目标的 destination 对象:
{
"rewrites": [{
"type": "service",
"service": "my_backend",
"path": "/api/$1"
}]
}
service 为服务名标识,path 是仅用于路由选择的路径,不会改变用户代码观测到的 URL。类型定义见 src/types.ts 的 ServiceDestination:
export type ServiceDestination = {
type?: 'service';
service: string;
/** Routing-only path used to select a route inside the target service. */
path?: string;
};
schemas.ts 中 serviceDestinationSchema 给出了服务名的约束:长度 1~64、匹配 ^<a href="https://link.gitcode.com/i/3072a6053343423597ea74ae924397e4" target="_blank">a-zA-Z</a>?$(必须以字母开头、字母数字或下划线/连字符结尾);path 最长 4096。
3.2 终止性语义:continue 与服务委托互斥
服务委托是**终止性(terminal)**交接——请求进入目标服务路由表后,不再在当前路由表继续匹配。因此 6.3.0 明确:continue: true 与服务 destination 同时出现会在规范化阶段被拒绝。对应的校验逻辑在 src/index.ts:
if (
route.destination &&
typeof route.destination === 'object' &&
route.continue
) {
errors.push(
`Route at index ${i} cannot define \`continue: true\` with a service \`destination\`. The service handoff is terminal.`
);
}
3.3 type 判别器变为可选(6.4.0)
6.4.0(PR 7cecf55)进一步降低书写成本:服务目标的格式判别改为依据 service 字段的存在,type: "service" 变为可选。因此上面的示例可简写为:
{
"rewrites": [{
"service": "my_backend",
"path": "/api/$1"
}]
}
convertRouteAliases() 中对应的处理是:当 destination 为对象且含字符串 service 时,规范化会自动补上 type: 'service',保证机器侧配置(规范化后的输出)始终包含 type: "service",保持规范形态。也就是说:手写配置可以省略 type,但规范化输出永远是完整显式的。
3.4 服务路由的归属范围(5.3.3)
5.3.3(PR #15018)对服务路由做了一系列工程化加固,相关实现集中在 src/service-route-ownership.ts:
- 修复路由归属作用域:父服务的 catch-all 路由(如 Vite SPA 回退
/:path*)不再捕获兄弟服务的前缀; - 将共享的归属守卫辅助函数
getOwnershipGuard、scopeRouteSourceToOwnership移入@vercel/routing-utils(在 src/index.ts 中统一导出); - 运行时服务函数输出被放到内部
/_svc/<service>/index命名空间下,避免文件系统路径泄露; /_svc被注册为服务校验中的保留路由前缀(reserved routePrefix),禁止普通路由占用;- 所有 builder 发出的路由(不限于路由归属 builder)在合并前都要先按服务归属约束作用域。
getOwnershipGuard 的实现逻辑(src/service-route-ownership.ts):
- 根服务(
/)会排除所有非根前缀:生成(?!prefix(?:/|$))负向前瞻序列; - 非根服务被约束在自己的前缀内,并排除其后代前缀:
(?=prefix(?:/|$))正向前瞻 + 后代负向前瞻。
scopeRouteSourceToOwnership 则把守卫包裹进 ^guard(?:source),并刻意用非捕获组保留原有捕获组的编号,避免影响 $1 反向引用。
四、规范化底层:normalizeRoutes 与相位校验
normalizeRoutes()(src/index.ts)是全部路由处理的咽喉。它依次完成:
- 别名折叠:
source/destination/statusCode→src/dest/status; - src 规范化:自动补
^前缀与$后缀、剥离转义的斜杠(\/→/)、并用new RegExp()校验正则合法性; - handle 相位校验:
handle路由只能有handle一个键;值必须在六个枚举内;同一handle不能重复出现; - 相位语义约束:
handle: hit之后:不允许定义dest/status,且必须continue: true;handle: miss之后:有dest则必须check: true,否则必须continue: true;
- 服务委托与 continue 冲突校验(6.3.0 新增,见 3.2 节)。
所有错误聚合后统一包装为 RouteApiError(code 为 invalid_route,附 vercel.link/routes-json 说明链接),最终返回 { routes, error } 二元组——调用方可根据 error 非空与否决定是否中断部署。
此外,getTransformedRoutes() 对 redirects/headers/rewrites 还会做三段式校验(源码 src/index.ts):
checkRegexSyntax:source能否编译为正则;checkPatternSyntax:destination中引用的:segment必须出现在source或has中,否则报invalid-route-destination-segment类错误;对request.pathtransform 还会用compilePathToRegexpTemplate预编译验证;checkRedirect:permanent与statusCode互斥。
五、transforms 与 env:请求路径/头部/查询参数改写
5.1 transforms 落地(5.0.8 → 5.3.0)
5.0.8 起 vercel.json 开始支持 transform 规则;5.3.0(PR #14223)为 transforms 增加 env 字段,允许在 args 中显式引用环境变量,运行时替换。
transformsSchema(src/schemas.ts)定义了四类 transform 类型与三类操作:
| type | op | 作用 |
|---|---|---|
request.headers |
append / set / delete |
改写请求头 |
request.query |
append / set / delete |
改写请求查询参数 |
response.headers |
append / set / delete |
改写响应头 |
request.path |
set(仅此一种) |
替换运行时可见的请求路径 |
allOf 条件约束(JSON Schema if/then)保证了合法性:
append/set操作必须提供args;request.headers/response.headers的set/append要求target.key匹配^[a-zA-Z0-9_-]+$,args限定在允许的 ASCII 字符集内;- 头部/查询类 transform 必须提供
target; request.pathtransform 不得提供target,args必须是 origin-form 路径(以/开头、不含//、不含?/#/空白/控制字符),最长 2048。
5.2 request.path 与 path-to-regexp 参数降级(6.3.1)
6.3.1(PR c4afec8)是 transforms 的一次重要深化:
request.path转换全面落地:routes 与高层 rewrites 都支持;- 参数降级(lowering):高层配置里的 path-to-regexp 参数(如
/:path*)会被编译为低层路由表的捕获引用(如/$1); @vercel/config在 router builder 中支持请求路径转换;@vercel/cli在 AI/手动编辑路由时保留请求路径转换语法与环境元数据。
底层实现是 compilePathToRegexpTemplate()(src/superstatic.ts):它把 source 编译出段名序列,模板中的 :param 段名映射为 $1、$2…(编号捕获),而 has 条件中的命名捕获保持命名(:tenant → $tenant);已有的 $N 与 env 引用原样保留。校验规则:模板引用了 source/has 中不存在的参数会抛错;若 $name 与路由参数同名且未列入 env 白名单,也会报错并提示改用 :name 语法或加入 env 白名单。
5.3 env 字段(5.3.1)
5.3.1(PR #14405)为 redirects、rewrites、routes 统一增加 env 字段(数组,最多 64 项,每项最长 256),声明 destination 或 headers 中需要在运行时以环境变量替换的变量名。它在 routes、rewrites、redirects 三个 schema 及类型定义(src/types.ts 的 RouteWithSrc/Rewrite/Redirect)中均有体现。
六、条件匹配与缓解动作:has / missing / mitigate(5.0.6)
5.0.6(PR #13409)为 has/missing/mitigate 增加 conditionValues 支持。hasSchema(src/schemas.ts)的要点:
has/missing均为数组,最多 16 项;- 支持
host(要求value)、header/cookie/query(要求key,value可选)三种类型; value既可以是字符串正则(命名组可被 destination 引用),也可以是条件操作对象:eq、neq、inc、ninc、pre(前缀)、suf(后缀)、re(正则)、gt/gte/lt/lte(数值比较);mitigate为{ action: 'challenge' | 'deny' },表示命中后的缓解动作。
(注:5.0.5 曾短暂 revert 过这批支持,5.0.6 重新落地;此后 has/missing 在 routes、rewrites、redirects、headers 各 schema 中均被引用。)
底层在 src/superstatic.ts 中:collectHasSegments() 会从 has 的正则值与 header 的 key 中收集可被 destination 引用的段名,并让 has 匹配优先于 source 匹配(indexes[name] = '$' + name);normalizeHasKeys() 会把 header 的 key 统一小写。
七、缓存语义与重写能力扩展
7.1 respectOriginCacheControl(5.3.2)
5.3.2 分别在 rewritesSchema(PR #14506)与 routesSchema(PR #14565)中增加 respectOriginCacheControl 布尔字段。语义(见 schema 描述):外部重写默认(true)尊重源站返回的 Cache-Control 头;设为 false 时对该重写禁用缓存。
7.2 statusCode on rewrites(3.1.0)
3.1.0(PR #10495)为 rewrites 增加 statusCode(100~999 整数),允许用重写覆盖响应状态码。在 rewritesSchema 中描述为"可选的覆盖响应状态码的整数",Rewrite 类型(src/types.ts)中同样存在。
7.3 bulk redirects 与 routes.json(5.2.x)
- 5.2.0(PR #14032)在 routing-utils 中支持 bulk redirects(批量重定向);同年 6.1.0 移除了
bulkRedirectsSchema(PR #14340),推测批量语义已被redirectsSchema的数组形态完全覆盖(redirects数组上限为 2048); - 5.2.1(PR #14138)实验性支持
routes.json文件;5.2.2(PR #14263)允许 routes 中的响应头值最长 32KB(schema 中headers的 valuemaxLength: 32768,与 headersSchema 一致); - 5.2.0 同时修复命名捕获组中下划线的支持(ECMA-262 规范本就允许,见
namedGroupsRegex = /\(\?<([a-zA-Z][a-zA-Z0-9_]*)>/g与 src/superstatic.ts 中的注释); - 5.0.2 将 routes schema 的路由数量上限更新为 2048。
7.4 redirect 的 source 支持域名(6.1.1)
6.1.1(PR #15670)允许 redirect 的 source 直接匹配完整域名。redirectsSchema 中 source 的描述即为:"匹配每个入站 pathname(不含 querystring)或包含域名的完整 URL"。
八、path-to-regexp 双版本对比机制(4.0.0 / 5.0.0 / 5.0.1 / 5.0.3)
4.0.0 升级了 path-to-regexp(PR #12734),5.0.0 又将其回退(PR #12746)。为避免升级引发隐性行为差异,包内实现了一套双版本并跑对比机制(见 src/superstatic.ts 顶部"Temporary double-install"注释):
- 同时引入
path-to-regexp(6.1.0)与path-to-regexp-updated(6.3.0); pathToRegexp()包装函数对同一 pattern 分别用两个版本编译,比较生成的正则字符串与参数 keys;- 存在差异或设置
FORCE_PATH_TO_REGEXP_LOG环境变量时,输出[vc] PATH TO REGEXP PATH DIFF @ #<callerId>与[vc] PATH TO REGEXP KEYS DIFF @ #<callerId>日志,用于在构建日志中观测升级影响面; - 当前调用统一返回现有(current)版本的编译结果,保证行为稳定。
因此 5.0.1/5.0.3 的"log diff"类变更,本质是这套对比观测机制的日志格式改进。
九、其他工程化变更
- 验证位置迁移(5.1.0,PR #13476):路由数组的校验从 schema 层迁移到 API 层,让错误信息与错误码(
invalid_redirect、invalid_rewrite、invalid_header等)在normalizeRoutes/getTransformedRoutes中统一产生,与 src/index.ts 的实现一致; - TypeScript 5.9(6.2.0,PR c56f851):包升级至 TypeScript 5.9 编译;
- TS 字面量类型推断(5.0.7,PR #13446):修复与
json-schema-to-ts的兼容性(schema 大量使用as const保证字面量类型); - 依赖打包修复(5.0.4,PR #13026):修复 dep bundling;
- 类型修正(6.0.1/6.0.2,PR #15292/#15318):修复 routes 中
source规范化引发的类型错误与 routes 类型中的拼写错误; - Node 版本基线(3.0.0,PR #10369):破坏性变更,放弃 Node.js 14,最低要求 Node.js 16;
- preferredRegion 回退(5.1.1,PR #13566):撤销对
preferredRegion的支持。
十、多来源路由合并:mergeRoutes 与 appendRoutesToPhase
除 normalizeRoutes 外,包还提供面向 builder 的路由编排能力:
mergeRoutes({ userRoutes, builds })(src/merge.ts):按handle相位把用户路由与各 builder(按use/entrypoint排序)产出的路由分组合并,同一相位内顺序为builder continue 路由 → 用户路由 → builder check 路由 → 其余路由;appendRoutesToPhase({ routes, newRoutes, phase })(src/append.ts):把新路由追加到指定handle相位段内;phase为null时插入到第一个 handle 之前。
十一、测试验证
包的测试位于 packages/routing-utils/test(index.spec.ts、superstatic.spec.ts、merge.spec.ts、append.spec.ts)。其中 index.spec.ts 对 respectOriginCacheControl、transforms、service 等关键字累计出现 163 处匹配,superstatic.spec.ts 对应 64 处,覆盖了服务 destination、路径转换、环境变量替换、条件匹配等核心路径的行为断言。执行方式:pnpm test(vitest,见 package.json 的 scripts)。
小结
从 3.0.0 到 6.4.0,@vercel/routing-utils 完成了三次关键跃迁:routes 去废弃(别名机制 + 与高层配置共存)、服务路由委托(service destination 对象 + 归属守卫 + /_svc 命名空间隔离)、路径转换与缓存语义(request.path transforms 参数降级、env 运行时替换、respectOriginCacheControl)。其设计主线始终是:手写配置追求简洁(type 可省略、别名友好),规范化输出追求规范(始终补全 type、折叠为 src/dest/status),校验策略追求早失败(schema + API 双层校验,错误码与 vercel.link 文档联动)。理解这份演进脉络,有助于在 vercel.json 中正确编排路由顺序、利用服务委托拆分多后端路由表,并在框架 builder 集成时对齐低层路由的捕获语法。