path-to-regexp 完全指南:把 `/user/:name` 路径模板转换为正则表达式
path-to-regexp 完全指南:把 /user/:name 路径模板转换为正则表达式
本篇技术指南围绕开源仓库 path-to-regexp 的核心能力展开:如何把 /user/:name、/*splat、/users{/:id}/delete 这类路径模板转换成可复用的匹配函数与正则表达式,并支持反向生成路径。读完本文,你将掌握 match、pathToRegexp、compile、parse、stringify 五大 API 的完整用法、全部配置项语义,以及参数名规则、可选片段、错误处理与 Express 老版本升级差异等实战细节,可直接落地到路由、URL 解析等场景。
安装与版本
在 Node.js 项目中安装:
npm install path-to-regexp --save
以当前仓库 package.json 为准,库版本为 8.4.2,发布包以 dist/index.js 为入口(exports/main 字段),同时提供 TypeScript 类型声明 dist/index.d.ts;体积约束严格,size-limit 将 dist/index.js 限制在 2 kB 以内(见 package.json)。
核心 API 一览
库对外导出五个函数,覆盖“解析 → 匹配 / 生成正则 / 反向编译 → 字符串化”的完整闭环(用法示例见 Readme.md):
const {
match, // 路径模板 -> 匹配函数
pathToRegexp, // 路径模板 -> 正则表达式 + keys
compile, // 路径模板 -> 反向生成路径的函数
parse, // 路径字符串 -> TokenData 中间表示
stringify, // TokenData -> 路径字符串
} = require("path-to-regexp");
路径语法速览
path-to-regexp 的核心是把一段路径字符串解析为三类元素:参数(:name)、通配符(*name) 与可选片段({...}),其余字符按纯文本处理。解析器位于 src/index.ts。
参数(Parameters)
参数用冒号前缀定义,如 :foo。它在一个路径段内匹配任意字符串,匹配范围到本段结束或遇到后续 token 为止:
const fn = match("/:foo/:bar");
fn("/test/route");
//=> { path: '/test/route', params: { foo: 'test', bar: 'route' } }
参数命名规则(源码依据见 src/index.ts 的 ID_START、ID_CONTINUE 正则):
- 可以是任意合法 JavaScript 标识符,如
:myName、:_、:café、:参数(Unicode 字符在ID_Start/ID_Continue范围内均可); - 也可以用双引号包裹以使用其他字符,如
:"param-name"、:"123"、:"0"; - 引号内支持转义,例如
:"1\"\2\"3"解析出的参数名是1"2"3(对应测试用例见 src/cases.spec.ts)。
通配符(Wildcard)
通配符与参数写法相同,但前缀改为星号(*foo),匹配跨多个路径段的一个或多个字符。匹配结果以数组形式返回,每个元素是经分隔符拆分后的一个段:
const fn = match("/*splat");
fn("/bar/baz");
//=> { path: '/bar/baz', params: { splat: [ 'bar', 'baz' ] } }
通配符返回数组的机制在 match 实现中可见:解码器会对捕获串按 delimiter 拆分后再逐个解码(src/index.ts)。
可选片段(Optional)
用花括号 {...} 把路径的一部分标记为可选,可以包裹参数、通配符和纯文本:
const fn = match("/users{/:id}/delete");
fn("/users/delete");
//=> { path: '/users/delete', params: {} }
fn("/users/123/delete");
//=> { path: '/users/123/delete', params: { id: '123' } }
可选片段可嵌套,也可灵活组合,例如 /name{/:attr1}{-:attr2}{-:attr3} 能依次匹配 name、name/1、name/1-2、name/1-2-3(对应用例见 src/cases.spec.ts)。实现上,解析器遇到 { 会递归调用 consumeUntil("}") 生成 group token(src/index.ts),生成正则时再通过 flatten 展开所有组合(src/index.ts)。
match:把路径模板变成匹配函数
match 返回一个函数,用于判断字符串是否命中路径模板,命中则返回 { path, params },否则返回 false:
- path:字符串、
TokenData对象,或由字符串与TokenData组成的数组(数组会被合并为多分支路由,见 src/cases.spec.ts)。 - options(可选,继承 pathToRegexp 的全部选项):
- decode:用于把匹配到的字符串解码为参数的函数,设为
false可禁用全部处理。默认值为decodeURIComponent。
- decode:用于把匹配到的字符串解码为参数的函数,设为
const fn = match("/foo/:bar");
解码环节在 src/index.ts 中实现:param 直接应用 decode,wildcard 则先按分隔符拆分成数组再逐个解码;返回的 params 对象通过 Object.create(null) 创建(不含原型污染风险)。典型行为:
match("/:test")("/caf%C3%A9");
//=> { path: '/caf%C3%A9', params: { test: 'café' } } // 默认 decodeURIComponent 解码
match("/:test", { decode: false })("/caf%C3%A9");
//=> { path: '/caf%C3%A9', params: { test: 'caf%C3%A9' } } // 保持原始编码
请注意:path-to-regexp 面向有序数据(例如路径、主机名),无法处理任意顺序的数据(例如查询字符串、URL fragment、JSON 等)。
pathToRegexp:生成正则与 keys
pathToRegexp 返回 { regexp, keys }:regexp 用于对路径做正则匹配,keys 是捕获组说明数组,用于理解 RegExp#exec 的每个匹配项:
- path:字符串、
TokenData对象,或二者的数组。 - options(可选,解析相关选项见 parse 与 TokenData):
- sensitive:是否区分大小写。默认
false(生成的表达式不带i标志,见 src/index.ts)。 - end:是否要求匹配到字符串末尾。默认
true;设为false时使用(?=delimiter|$)前瞻代替$,用于“非结尾”匹配(src/index.ts)。 - delimiter:路径段的默认分隔符,例如
:named参数在[^/]中的/。默认'/',可用于匹配主机名(如delimiter: ".")。 - trailing:是否允许匹配末尾的可选分隔符。默认
true,即/test也能命中/test/。
- sensitive:是否区分大小写。默认
const { regexp, keys } = pathToRegexp("/foo/:bar");
regexp.exec("/foo/123"); //=> ["/foo/123", "123"]
keys 中的元素类型为 param 或 wildcard(源码定义见 src/index.ts),Key = Parameter | Wildcard。例如 pathToRegexp("/foo/:bar") 的 keys 为 [{ type: "param", name: "bar" }],与 regexp.exec 结果中索引 1 的捕获组一一对应。
compile:反向生成路径(“反向”模式)
compile 返回一个函数,把参数对象转换为合法的路径字符串:
- path:字符串或
TokenData对象。 - options(解析相关选项见 parse 与 TokenData):
- delimiter:路径段默认分隔符,默认
'/'。 - encode:编码输入字符串以输出到路径中的函数,设为
false则完全禁用编码。默认encodeURIComponent。
- delimiter:路径段默认分隔符,默认
const toPath = compile("/user/:id");
toPath({ id: "name" }); //=> "/user/name"
toPath({ id: "café" }); //=> "/user/caf%C3%A9"
const toPathRepeated = compile("/*segment");
toPathRepeated({ segment: ["foo"] }); //=> "/foo"
toPathRepeated({ segment: ["a", "b", "c"] }); //=> "/a/b/c"
// 禁用 encode 时,需要确保输入已经正确编码,且不接受数组。
const toPathRaw = compile("/user/:id", { encode: false });
toPathRaw({ id: "%3A%2F" }); //=> "/user/%3A%2F"
实现层面,compile 把 tokens 逐个转换为编码器,通配符值必须是非空字符串数组,由 delimiter 连接;普通参数必须是非空字符串(src/index.ts)。对应错误行为(测试见 src/index.spec.ts):
- 缺少必传参数时抛出
TypeError: Missing parameters: b; - 通配符传空数组/非数组时抛出
TypeError: Expected "foo" to be a non-empty array; - 普通参数传数组或空串时抛出
TypeError: Expected "foo" to be a non-empty string; - 可选片段(group)在参数缺失时静默省略,例如
compile("{/:test}")({})返回""。
stringify:把 TokenData 还原成路径字符串
stringify 接收一个 TokenData 对象,输出对应的 path-to-regexp 语法字符串:
- data:一个
TokenData对象。
const data = {
tokens: [
{ type: "text", value: "/" },
{ type: "param", name: "foo" },
],
};
const path = stringify(data); //=> "/:foo"
实现见 src/index.ts:text 会经过 escapeText 转义保留字符({}()<a href="https://link.gitcode.com/i/9b932409531078b218aafdb7823cc860" target="_blank">]+?!:*\\ 等),group 还原为 {...},param/wildcard 还原为 :/* 前缀,参数名不符合标识符规则时自动加引号。parse → stringify → parse 的往返一致性由 [src/cases.spec.ts 中的 STRINGIFY_TESTS 用例保证。
parse 与 TokenData:语法树中间层
parse 接受字符串并返回 TokenData,后者可直接传给 match、compile、pathToRegexp:
- path:一个字符串。
- options(可选):
- encodePath:用于编码输入字符串的函数。默认
x => x(恒等函数),官方推荐配合 encodeurl 与 src/index.ts。
- encodePath:用于编码输入字符串的函数。默认
TokenData 有两个属性(src/index.ts):
- tokens:token 序列,目前包含四种类型(定义见 src/index.ts):
text:纯文本,如{ type: "text", value: "/" };param:段内参数,如{ type: "param", name: "foo" };wildcard:跨段通配符,如{ type: "wildcard", name: "splat" };group:可选片段,含子 token 序列,如{ type: "group", tokens: [...] }。
- originalPath:调用
parse时的原始路径,会出现在错误信息中,便于定位问题。
自定义 path(Custom path)
某些场景下无法使用 path-to-regexp 的字符串语法,但仍想使用其 match/compile 能力。此时可直接构造 TokenData 传入(示例见 Readme.md):
import { match } from "path-to-regexp";
const tokens = [
{ type: "text", value: "/" },
{ type: "param", name: "foo" },
];
const originalPath = "/[foo]"; // 用于辅助调试错误信息。
const path = { tokens, originalPath };
const fn = match(path);
fn("/test"); //=> { path: '/test', params: { foo: 'test' } }
错误处理与升级兼容
为消除历史版本中模棱两可的路径写法,当前版本会主动抛出错误。所有解析/编译错误都通过 PathError(继承自 TypeError)抛出,消息包含 originalPath 与调试指引链接(实现见 src/index.ts,错误用例见 src/index.spec.ts)。
Missing parameter name(缺少参数名)
: 或 * 之后必须紧跟参数名,例如 /*path。参数名可以是合法 JavaScript 标识符(如 :myName),也可以是用双引号包裹的字符串(如 :"my-name")。例如 parse("/:/") 会抛出 Missing parameter name at index 2。
Unexpected ? or +(意外的 ? 或 +)
旧版本用 ?、*、+ 表示可选或重复参数,当前版本不再支持。替代写法:
- 可选(原
?):使用花括号,如/file{.:ext}; - 一个或多个(原
+):使用通配符,如/*path; - 零个或多个(原
*):两者结合,如/files{/*path}。
Unexpected (, ), [, ] 等(意外字符)
旧版本用这些字符表达正则特性,本版本不再支持并将它们保留以消除歧义,直接使用会抛错。如需按字面匹配这些字符,用反斜杠转义即可,例如 "\("。测试覆盖见 src/cases.spec.ts:"/.\\+\\*\\?\\{\\}=^\\!\\:$\\[\\]\\|" 可命中 /.+*?{}=^!:$[]|。
Unterminated quote(引号未闭合)
参数名可用双引号包裹,此错误表示忘记闭合引号。例如 parse('/:"foo') 会抛出 Unterminated quote at index 2。
Express <= 4.x 兼容性差异
与 Express <= 4.x 相比,本版本在以下方面打破兼容:
- 通配符
*必须命名,且行为与参数:一致; - 不再支持可选字符
?,改用花括号:/:file{.:ext}; - 不再支持正则表达式字符;
- 部分字符被保留以避免升级时的混淆:
()[]?+!; - 参数名现在支持合法 JavaScript 标识符,或引号包裹写法如
:"this"。
开发实践建议
来自 Readme.md 的官方建议:
- 如果你在用
match和compile重写路径(即原样搬运路径内容),考虑同时使用encode: false和decode: false,让原始路径原样传递、不做编解码; - 若要确保匹配包含通常会被编码的字符(如 emoji)的路径,可以为
encodePath接入 encodeurl 这类专用编码函数。
工程化保障:测试、性能与体积
仓库围绕这些 API 建立了完整的质量保障体系,可作为使用时的行为契约参考:
- 单元测试:src/index.spec.ts 覆盖
PathError、解析错误、编译错误、正则错误与字符串化错误;src/cases.spec.ts 收录了 2480 行参数化用例(PARSER_TESTS、COMPILE_TESTS、MATCH_TESTS、STRINGIFY_TESTS),涵盖主机名匹配、Unicode、多字符分隔符、数组路径、前后缀参数组合等边界场景; - ReDoS 防护:src/redos.spec.ts 使用
recheck库对每个字符串路径生成的 regexp 做安全性检查,断言状态为safe,防止引入灾难性回溯的正则; - 性能基准:src/index.bench.ts 使用 vitest bench 对
parse、pathToRegexp、match(含 3.2 万字符超长路径、易回溯模式)与compile做基准测试; - 体积控制:见 package.json 的
size-limit配置(dist/index.js≤ 2 kB)。
License
MIT(见 LICENSE)。