URLPattern 怎么同时匹配域名和路径参数

要让 URLPattern 同时匹配域名和路径参数，最直接的写法是使用对象构造模式：把域名规则放在 hostname，把路径规则放在 pathname，再从 exec() 返回值的对应组件中分别读取命名分组。比如 :tenant.example.com 可以捕获租户子域，/projects/:projectId 可以捕获项目编号，两者由同一条模式共同约束。

官方资料：https://developer.mozilla.org/en-US/docs/Web/API/URLPattern

核心规则只有一句：模式按 URL 组件声明，结果也按 URL 组件读取。域名中的 tenant 在 result.hostname.groups，路径中的 projectId 在 result.pathname.groups，不要把它们当成同一个扁平参数对象。

先明确 URLPattern 的组件匹配模型

传统写法常先用 new URL() 解析地址，再分别写域名正则和路径正则。逻辑本身没有错，但规则容易散落：域名限制写在一处，路径参数提取写在另一处，协议校验又在第三处。URLPattern 的价值是把这些组件规则放进一个可复用对象中。

URL 不是一整段不可分割的文本。它包含 protocol、username、password、hostname、port、pathname、search 和 hash 等组件。对象模式只需声明真正关心的组件；未声明的组件默认保持通配，不会妨碍匹配。本文显式写入 protocol、hostname 和 pathname，这样规则边界更清楚。

命名参数使用 :name。在 hostname 中，普通命名参数默认不会跨过点号，因此 :tenant.example.com 对应一个子域标签；在 pathname 中，普通命名参数默认不会跨过斜杠，因此 /projects/:projectId 对应一个路径段。这正适合多租户项目地址。

用对象模式同时约束 hostname 和 pathname

下面的模式要求协议为 HTTPS、域名必须是一个租户子域加 example.com，路径必须是 /projects/项目编号：

// 同时约束协议、租户子域和项目路径。
const projectRoute = new URLPattern({
  protocol: "https",
  hostname: ":tenant.example.com",
  pathname: "/projects/:projectId",
});

// exec() 匹配成功时返回结构化结果，失败时返回 null。
const match = projectRoute.exec(
  "https://acme.example.com/projects/42"
);

if (match) {
  // hostname 与 pathname 的分组需要分别读取。
  console.log(match.hostname.groups.tenant); // acme
  console.log(match.pathname.groups.projectId); // 42
}

这条地址的域名部分匹配 :tenant.example.com，所以 tenant 得到 acme；路径部分匹配 /projects/:projectId，所以 projectId 得到 42。只有各个已声明组件都匹配，整条 URL 才匹配。

如果只想判断是否匹配，可以调用 test()：

// 只需要布尔值时使用 test()。
const accepted = projectRoute.test(
  "https://acme.example.com/projects/42"
);

console.log(accepted); // true

但业务最终还要读取参数时，不必先 test() 再 exec()。直接调用一次 exec() 并判断是否为 null，即可同时完成判断和提取，代码更短，也避免重复匹配。

exec 结果为什么要分组件读取

exec() 的结果不是一个只有 groups 的普通正则结果，而是一个按 URL 组件组织的对象。每个组件都有自己的 input 和 groups。因此下面这种扁平读取方式并不存在：

// 错误思路：结果顶层没有统一的 groups。
const result = projectRoute.exec(
  "https://acme.example.com/projects/42"
);

// result.groups.tenant 不是 URLPattern 的结果结构。

正确方式是先判断结果，再进入对应组件：

// 匹配失败时立即返回，避免访问 null。
function readProjectAddress(input) {
  const result = projectRoute.exec(input);

  if (!result) {
    return null;
  }

  // 域名参数从 hostname.groups 读取。
  const tenant = result.hostname.groups.tenant;

  // 路径参数从 pathname.groups 读取。
  const projectId = result.pathname.groups.projectId;

  return { tenant, projectId };
}

result.inputs 保存参与匹配的输入，result.hostname.input 与 result.pathname.input 则分别反映组件输入。调试规则时，这些字段可以帮助判断问题究竟出在域名、路径还是输入基准上。

处理相对 URL、可选子域与更严格参数

相对路径必须提供 baseURL

完整地址本身包含协议和域名，可以直接交给 exec()。相对路径没有域名上下文，如果模式同时约束 hostname，就需要提供基准地址：

// 相对输入通过第二个参数补齐协议和域名。
const relativeMatch = projectRoute.exec(
  "/projects/42",
  "https://acme.example.com"
);

if (relativeMatch) {
  // 补齐后仍然可以读取域名与路径命名分组。
  console.log(relativeMatch.hostname.groups.tenant); // acme
  console.log(relativeMatch.pathname.groups.projectId); // 42
}

只传 /projects/42 而不传基准地址，模式无法凭空知道应该使用哪个域名。对于单页应用中的站内相对地址，可以把当前站点地址或业务允许的固定站点作为 baseURL；不要用不受信任的基准地址绕过原本的域名限制。

项目编号需要纯数字时收紧模式

普通 :projectId 可以匹配任意非斜杠路径段。若业务只接受数字编号，可以在命名参数后加入自定义正则：

// 双反斜杠用于在 JavaScript 字符串中表达正则的 \d。
const numericProjectRoute = new URLPattern({
  protocol: "https",
  hostname: ":tenant.example.com",
  pathname: "/projects/:projectId(\\d+)",
});

// 数字项目编号可以匹配，字母编号会得到 null。
const numericResult = numericProjectRoute.exec(
  "https://acme.example.com/projects/42"
);

模式应该只表达稳定的地址结构。像“项目是否存在”“当前用户是否有权限”这类业务判断仍应在匹配之后完成，不能把路由匹配当成授权校验。

根域名与多级子域是另一条规则

:tenant.example.com 明确要求只有一个租户标签，因此 example.com 没有租户参数，不应匹配；team.eu.example.com 又多了一层，也不应被当成同一地址结构。若业务确实允许根域名或多级子域，应单独设计可选或重复模式，并为每种输入写清楚预期，而不是把单标签参数误解为“任意前缀”。

为旧环境准备兼容回退

URLPattern 已进入现代 Web 平台，但旧设备或旧运行时仍可能没有该全局对象。页面启动时先做能力检测，支持时使用组件化模式，不支持时退回 URL 解析和两条边界明确的正则：

// 在支持 URLPattern 的环境中复用前面的组件模式。
function matchProjectURL(input) {
  if ("URLPattern" in globalThis) {
    const result = projectRoute.exec(input);

    if (!result) {
      return null;
    }

    return {
      tenant: result.hostname.groups.tenant,
      projectId: result.pathname.groups.projectId,
    };
  }

  // 旧环境先用 URL 可靠拆分组件，再分别校验域名和路径。
  const url = new URL(input);
  const hostMatch = /^(?[^.]+)\.example\.com$/.exec(
    url.hostname
  );
  const pathMatch = /^\/projects\/(?[^/]+)$/.exec(
    url.pathname
  );

  if (!hostMatch || !pathMatch) {
    return null;
  }

  return {
    tenant: hostMatch.groups.tenant,
    projectId: pathMatch.groups.projectId,
  };
}

回退分支仍然先用 URL 拆组件，而不是直接对完整地址做一个巨大正则。这样协议、端口、查询参数或哈希不会意外混进域名与路径参数中，规则也更容易与 URLPattern 版本保持一致。

常见问题

为什么 result.hostname.groups 有值，result.groups 却报错？

因为 URLPattern 的匹配结果按 URL 组件保存。域名参数位于 hostname.groups，路径参数位于 pathname.groups，顶层没有统一的 groups。

只匹配路径时还要写 hostname 吗？

不需要。只声明 pathname 时，未声明的组件保持通配。但当规则用于多租户、回调地址或边缘路由时，域名通常是安全边界的一部分，应把 hostname 明确写进同一条模式。

test() 和 exec() 应该怎么选？

只关心“是否匹配”时用 test()；还要读取 tenant、projectId 等参数时直接用 exec()，并判断返回值是否为 null。

URLPattern 能代替权限校验吗？

不能。它只负责判断地址结构并提取参数。租户是否有效、项目是否存在、当前用户能否访问，都必须由后续业务逻辑或服务端授权完成。