JavaScript URLPattern 怎样匹配带命名参数的路径

处理前端路由时，URLPattern 可以把“路径结构”和“参数读取”放在同一个声明里。最小写法是 new URLPattern({ pathname: "/users/:id" })：先用 test() 判断是否命中，再用 exec() 读取 result.pathname.groups.id。关键点是命名组属于具体 URL 组件，不能写成不存在的 result.groups.id。

从手动拆路径改成 URLPattern 声明

传统做法通常是先读取 location.pathname，再调用 split("/")，最后按数组下标解释每一段。路径稍微加入可选段、主机限制或正则条件，这种代码就容易把“第几段”与“它代表什么”绑死。URLPattern 的模式直接描述路径语义，更适合把路由规则交给一个可复用对象。

下面的模式只绑定 pathname，含义是路径必须包含 /users/，后面再跟一个命名为 id 的段：

// 命名组 id 只负责捕获用户路径段
const userPattern = new URLPattern({
  pathname: "/users/:id"
});

用 test 判断命中，再从 pathname.groups 取参数

只需要分流时使用 test()；需要参数时使用 exec()。不要用一次 exec() 的返回值去代替所有判断，因为失败时它是 null，直接读取属性会抛出异常。

// 先判断完整 URL 是否命中，再读取 pathname 下的命名组
const url = "https://example.com/users/42?tab=posts";

if (userPattern.test(url)) {
  const result = userPattern.exec(url);
  const userId = result.pathname.groups.id;
  console.log(userId); // 42
} else {
  console.log("不是用户详情路径"); // 未命中时不读取 groups
}

这里的 search 查询串不会被 pathname 模式吞掉，id 仍然只得到 42。如果模式不匹配，exec() 返回 null；生产代码可以直接以空值分支处理：

// 用可选链把不匹配转换成可判断的空值
const result = userPattern.exec("https://example.com/assets/app.js");
const userId = result?.pathname.groups.id;
console.log(userId ?? "未找到用户 ID"); // 未找到用户 ID

给命名参数增加正则约束

默认的路径命名组会匹配当前段里的普通字符。如果订单编号必须是数字，可以在命名组后写正则约束。JavaScript 字符串里的反斜杠需要再转义一次，因此数字表达式应写成 \\d+：

// 只允许一个或多个数字作为订单 ID
const orderPattern = new URLPattern({
  pathname: "/orders/:id(\\d+)"
});

const numericOrder = orderPattern.exec("https://example.com/orders/2026");
const textOrder = orderPattern.exec("https://example.com/orders/abc");
console.log(numericOrder?.pathname.groups.id); // 2026
console.log(textOrder); // null：abc 不满足数字约束

这个限制属于匹配规则本身，后续业务不必再写一套“是否全是数字”的重复判断。若编号允许字母和短横线，就应调整正则，而不是先放宽模式再依赖业务层补救。

斜杠、主机和大小写是三个独立边界

pathname 的值以 / 开头；把模式写成 "users/:id" 不能替代 "/users/:id"。命名组默认不跨越路径分隔符，所以 /users/42/profile 不会被上面的单段模式当成一个用户 ID。

如果需要限制主机，应同时声明 hostname，或者使用包含主机的完整模式。默认匹配区分大小写；只有业务确实允许大小写不敏感时才打开 ignoreCase：

// 主机、路径和大小写策略一起写清楚
const docsPattern = new URLPattern(
  {
    hostname: "docs.example.com",
    pathname: "/guide/:section"
  },
  { ignoreCase: true } // 只在路由约定允许时启用
);

console.log(docsPattern.test("https://DOCS.EXAMPLE.COM/Guide/start")); // true

兼容性与采用建议

URLPattern 是 Web 平台 API，MDN 当前将它标记为 Baseline 2025，并提示较旧设备或浏览器可能不支持。上线前应按项目支持矩阵做能力检测；若不能接受旧环境缺失，就保留原有路由解析方案作为降级路径。不要把“能构造对象”误当成“所有目标浏览器都可用”。

采用时可以遵循一个简单边界：固定结构交给 URLPattern，业务权限、资源是否存在和参数类型转换仍在命中之后处理。这样模式负责“这是不是目标路径”，业务代码负责“这个 ID 能不能继续使用”，两层职责更容易测试和维护。

常见问题

命名参数为什么不在 result.groups 里？

因为 URLPattern 按 URL 组件组织结果。路径参数在 result.pathname.groups，主机参数则在 result.hostname.groups。

URLPattern 的 test() 能直接返回参数吗？

不能。test() 只返回布尔值；要拿命名参数必须调用 exec()，并处理它返回 null 的情况。

为什么 /users/:id 没有匹配多级路径？

路径命名组默认只匹配一个段，不包含斜杠。多级路径应显式设计模式，不要把单段参数当成任意深度通配符。

资料：MDN URL Pattern API；WHATWG URL Pattern Standard。两者用于核对命名组、test()、exec()、组件边界和大小写选项。