前端 URLPattern 怎样按命名参数匹配路由路径

前端路由里最容易写错的一步，是把“路径能不能匹配”和“匹配出来的参数是什么”混成一件事。现在浏览器提供的 URLPattern 可以把这两件事放在同一个路径模式里：用 /users/:userId/posts/:postId 描述结构，再从 exec() 的命名组中取值。

官方资料地址：https://developer.mozilla.org/en-US/docs/Web/API/URL_Pattern_API。本文只讨论路径模式、命名参数、test、exec 和兼容降级，不展开完整路由框架。

如果只想判断一条 URL 是否符合模式，用 test()；如果还要拿到 userId 这类参数，用 exec() 并读取对应 URL 组件下的 groups。

URLPattern 解决的是路径结构，不是字符串包含

我第一次把它放进路由判断时，最明显的变化是不用再手写多次 split('/')。模式里的字面量负责固定片段，冒号开头的名字负责捕获一个路径片段；pathname 本身必须从斜杠开始，少了开头的斜杠，模式就不是同一个路径。

命名组也让代码意图更清楚：:userId 不是要匹配的固定文字，而是“把这一段交给 userId”。它仍然只描述匹配关系，不替你完成权限判断、数据查询或页面跳转。

用命名组读取 pathname 参数

下面的例子把用户编号和文章编号都写进路径模式。代码中的输出是读者按示例输入推导出的预期值，并非本文制作时运行得到的截图。

const articleRoute = new URLPattern({
  // 命名组只负责捕获 pathname 中对应的路径片段。
  pathname: "/users/:userId/posts/:postId",
});

const inputPath = "/users/42/posts/9001";
const match = articleRoute.exec({ pathname: inputPath });

if (!match) {
  throw new Error("路径不符合文章路由模式"); // 不匹配时不要读取 groups。
}

const params = match.pathname.groups;
console.log(params.userId, params.postId); // 预期：42 9001

exec() 返回的是按 URL 组件分组的结果，所以这里读取的是 match.pathname.groups，不是直接读取 match.groups。如果命名组改成 :articleId，下游读取也必须同步改名；这种显式关系比按数组下标取值更不容易错。

test 和 exec 怎么分工

只做门禁判断时，test() 返回布尔值，适合回答“这条路径是不是这一类页面”。需要继续渲染页面或请求数据时，再使用 exec() 取得命名参数。不要为了拿一个布尔结果而解析完整对象，也不要调用 exec() 后忘记处理返回值为 null 的情况。

查询串、正则约束和浏览器兼容要分开看

pathname 匹配的是路径部分，?page=2 属于查询串，不会自动成为命名参数。如果业务同时关心查询串，应让 URL 负责解析它。需要限制编号为数字时，可以在命名组上增加正则约束，但这会让模式更难读，只有边界确实需要时再加。

const numericRoute = new URLPattern({
  // 只允许数字文章编号，反斜杠在 JS 字符串中需要转义。
  pathname: "/posts/:postId(\\d+)",
});

const parsed = new URL("https://example.com/posts/9001?page=2#comments");
const matched = numericRoute.exec(parsed.href);

if (matched) {
  // 路径参数与查询参数分层读取，避免把 page 当成 pathname 参数。
  console.log(matched.pathname.groups.postId, parsed.searchParams.get("page"));
}

MDN 将 URL Pattern API 标为 Baseline 2025，但较旧设备和浏览器仍可能不支持。生产代码可以先判断 globalThis.URLPattern，不支持时用 URL 读取 pathname，再由已有路由层或明确的分段规则处理降级逻辑。

function getPathname(urlText) {
  // 兼容分支只负责拿到 pathname，不伪装成完整 URLPattern 实现。
  return new URL(urlText, location.origin).pathname;
}

const pathname = getPathname("/users/42/posts/9001");
if (typeof globalThis.URLPattern === "undefined") {
  // 旧环境下把 pathname 交给项目已有的路由匹配器。
  console.log(pathname);
}

我会怎样把这条规则放进项目

我的取舍是把模式定义放在路由表附近，把 test 当作快速筛选，把 exec 的结果转换成项目自己的参数对象；查询串继续交给 URLSearchParams。这样既保留浏览器 API 的清晰边界，也不让页面组件直接依赖底层返回对象。

• 模式从 pathname 的斜杠开始，命名组名称与读取字段保持一致。
• 只判断时用 test()，需要参数时检查 exec() 的空结果。
• 路径、查询串、锚点分别由对应组件读取，不把它们拼成一个模糊字符串。
• 支持范围不确定时保留 URL 降级，并把降级职责限定在路径解析。

两个容易混淆的问题

为什么 match.groups 读不到参数？ 因为结果按 URL 组件分组，路径命名组在 match.pathname.groups 下；查询串和锚点有各自的结果位置。

URLPattern 能代替整个路由框架吗？ 不能。它提供 URL 模式匹配和捕获组，页面加载、权限、数据请求、历史记录和兼容策略仍然属于应用自己的路由层。

把模式、匹配检查和参数读取拆开后，URLPattern 的价值就很具体：它减少了手写路径分割，同时保留了清晰的边界；遇到旧环境时，再用 URL 做有限降级。