URLPattern 怎么做前端路由匹配：命名参数、URL 校验与兼容降级

前端路由一旦同时处理路径参数、查询串和完整 URL，单靠几段正则很快就会出现“能匹配但取不到参数”的分叉。URLPattern 把这些规则放回 URL 的各个组成部分里，适合用来做轻量路由表、链接校验和渐进增强。

最小用法是先用 test() 判断 URL 是否命中，再用 exec() 读取命名参数；上线前用 typeof URLPattern 做能力检测，并保留旧路由函数作为降级路径。

先把一条用户路由写成可验收的规则

假设页面需要识别用户详情地址：https://example.test/users/42?tab=posts。规则只关心主机、路径和查询参数，先不把所有导航都塞进一个大正则。

const userRoute = new URLPattern({
  protocol: 'https',
  hostname: 'example.test',
  pathname: '/users/:id',
  search: 'tab=:tab'
});

const href = 'https://example.test/users/42?tab=posts';

if (userRoute.test(href)) {
  console.log('route matched');
}

这里的验收结果很明确：https://example.test/users/42?tab=posts 返回 true；主机换成 cdn.example.test 或路径缺少用户编号时返回 false。规则对象也比“先截字符串再猜字段”更容易审查。

为什么命名参数比手写分组更稳

命名组用冒号开头。匹配成功后，结果按 URL 部分分开保存，路径参数在 pathname.groups，查询参数在 search.groups，不会因为正则增删一个分组就让下标整体错位。

const result = userRoute.exec(href);

if (result) {
  const userId = result.pathname.groups.id;
  const tab = result.search.groups.tab;
  console.log({ userId, tab });
}

上面这次验收应看到 { userId: '42', tab: 'posts' }。如果业务只需要判断当前链接是不是用户页，用 test() 就够了；只有需要驱动页面数据请求时才读取 exec() 的结果。

规则匹配的边界要提前写进代码

URLPattern 解决的是模式匹配，不会替业务替你决定参数是否合法。比如 /users/:id 能匹配字符串 abc，但后端若要求数字 ID，就要在取出参数后再做校验。

function matchUser(href) {
  const result = userRoute.exec(href);
  if (!result) return null;

  const id = result.pathname.groups.id;
  if (!/^\d+$/.test(id)) return null;
  return { id, tab: result.search.groups.tab || 'overview' };
}

console.log(matchUser(href));

把“路由命中”和“参数可用”拆开，失败状态更好解释：前者是导航分流问题，后者是业务字段问题。查询串也可以设置默认值，但不要把非法值默默当成默认值，否则错误链接会被隐藏。

浏览器暂不支持时怎么降级

URLPattern 的标准化推进并不等于所有目标浏览器都同时具备同样能力。入口处先检查构造器，支持时使用新规则，不支持时回到已有的路由解析函数。

function matchRoute(href) {
  if (typeof URLPattern === 'function') {
    const result = userRoute.exec(href);
    if (!result) return null;
    return {
      id: result.pathname.groups.id,
      tab: result.search.groups.tab || 'overview'
    };
  }

  return legacyMatchUser(href);
}

降级函数要和新规则共享同一组验收用例：命中详情页、缺少 ID、错误主机、空查询串各测一次。这样切换实现不会悄悄改变导航结果，也不会因为某个浏览器没有 API 就让整个入口报错。

构造器和匹配调用的几个坑

相对模式要配基准 URL

如果模式没有完整的协议和主机，调用时需要明确它相对于哪个 URL 解析。团队代码里最好统一使用对象写法，或在封装层固定基准，避免开发环境和生产域名被意外混用。

不要把 URL 解码和业务校验混为一谈

路由参数可能经过 URL 编码。先让匹配器完成 URL 语义上的分段，再在业务边界做允许字符、长度和类型检查；涉及资源权限时仍然以服务端校验为准。

不要用一条规则吞掉所有页面

用户详情、设置页和搜索页的参数契约不同，分成几条小规则更便于测试。路由表可以按顺序匹配，但要把更具体的规则放在通用规则前面。

最小验证清单

发布前可以在目标浏览器控制台跑下面的断言，确认新旧实现的结果一致：

console.assert(userRoute.test('https://example.test/users/42?tab=posts'));
console.assert(!userRoute.test('https://example.test/users/42'));
console.assert(!userRoute.test('https://cdn.example.test/users/42?tab=posts'));
console.assert(matchUser('https://example.test/users/abc?tab=posts') === null);

如果第一条失败，先检查模式的 hostname、pathname 和 search 是否和实际地址一致；如果第四条没有返回空值，再检查参数校验是否放在匹配成功之后。

图中把模式拆成 URL 组成部分，便于对照 test() 的布尔判断和 exec() 的命名结果。

第二张图强调降级不是隐藏错误，而是让两套实现共享命中、缺参、错误主机和非法 ID 四组结果。

相关问题

URLPattern 能替代后端路由校验吗？

不能。它适合浏览器侧导航分流和输入形状判断，权限、资源存在性和最终参数校验仍由服务端负责。

什么时候继续用正则更合适？

如果只处理一个已经取出的字符串片段，短正则可能更直接；当规则同时涉及协议、主机、路径和查询串时，按 URL 部分描述通常更清楚。

只需要判断是否命中时该调用什么？

调用 test()。需要命名参数或各 URL 部分的匹配值时，再调用 exec()，并对返回值为空的情况做分支。

小结

URLPattern 的价值不在于把所有路由代码换成新 API，而是让规则、参数和验收边界集中在一个可读对象里。先用 test() 做分流，命中后用 exec() 取命名参数，再用能力检测和共享用例兜住降级路径，迁移成本会更可控。