React Router useHref 全面解析：从 to 值到 href 字符串的完整解析链路

useHref 是 React Router（framework / data / declarative 三种模式均可用）提供的核心 Hook，负责把 <Link>、<NavLink> 等组件传入的 to 相对路径，基于当前路由位置与 basename 解析成可以直接写入 <a href> 的绝对路径字符串。阅读本文后，你将掌握 useHref 的函数签名、参数语义、内部解析原理（route 相对与 path 相对两种模式），并能熟练应对嵌套路由、带 basename 部署、尾部斜杠、.. 回溯等实战场景。

useHref 是什么：to 与 href 的分界点

在 React Router 的 API 设计中，"to 值" 和 "href" 是两个刻意区分开的概念。一个 <a href> 中的地址是"基于当前 URL 段的相对定位"；而 <Link to> 这类 to 值则是"基于路由树的相对定位"——这正是为什么官方文档强调这是一种 to 值而非 href（参见 源码注释）。

useHref 正是两者的桥梁：

import { useHref } from "react-router";

function SomeComponent() {
  let href = useHref("some/where");
  // 返回一个已解析的绝对 href，例如 "/resolved/some/where"
}

它的官方定位一句话即可概括：将给定的路径基于当前的 Location 进行解析（"Resolves a URL against the current Location"）。该文档同时标注了其适用模式为 [MODES: framework, data, declarative]，意味着无论你使用 framework 路由（如通过 routes.ts 组织的完整框架应用）、data 路由（RouterProvider + createBrowserRouter），还是声明式路由（<BrowserRouter> + <Routes>），useHref 都以相同语义工作。

函数签名与参数语义

useHref 在仓库中的完整源码级签名为（见 hooks.tsx）：

export function useHref(
  to: To,
  { relative }: { relative?: RelativeRoutingType } = {},
): string

to

To 类型既可以是字符串，也可以是包含 pathname / search / hash 的对象形式。解析时若传入字符串会先经 parsePath 拆分成这三个字段（见 resolveTo 源码）；若传入对象，源码会对字段做合法性校验——pathname 中不允许包含 ? 或 #，search 中不允许包含 #，否则会抛出 getInvalidPathError 提示你把对应部分放进正确的字段。

例如 useHref({ pathname: "some/where", search: "?a=b", hash: "#h" }) 与 useHref("some/where?a=b#h") 是等价的。

options.relative

这是第二个参数（函数名为 options，实际属性为 relative），默认值为 "route"。类型定义在路由核心中为：

export type RelativeRoutingType = "route" | "path";

（见 router.ts）。其语义（沿自文档）为：

取值	行为	说明
"route"（默认）	相对路由树解析	路由路径基于路由层级，而非 URL 路径段；每个前导 .. 表示"上溯一级路由"，而非"上一个 URL 段"
"path"	相对路径段解析	相对当前 URL 的路径段工作，更接近浏览器原生 <a href> 的行为

返回值

一个已解析好的 href 字符串。注意区分：useResolvedPath 与此类似，但返回的是包含 pathname、search、hash 字段的 Path 对象，而 useHref 直接产出可用于渲染的字符串。

内部实现原理：四步解析链路

从源码看，useHref 的实现非常简洁，共分四步（hooks.tsx）：

export function useHref(to, { relative } = {}): string {
  invariant(
    useInRouterContext(),
    `useHref() may be used only in the context of a <Router> component.`,
  );

  let { basename, navigator } = React.useContext(NavigationContext);
  let { hash, pathname, search } = useResolvedPath(to, { relative });

  let joinedPathname = pathname;

  // If we're operating within a basename, prepend it to the pathname...
  if (basename !== "/") {
    joinedPathname =
      pathname === "/" ? basename : joinPaths([basename, pathname]);
  }

  return navigator.createHref({ pathname: joinedPathname, search, hash });
}

1. Router 上下文守卫

首先调用 useInRouterContext()（其实现见 hooks.tsx），通过检查 LocationContext 是否存在来确保组件渲染在 <Router> 内部。若不在 Router 上下文中，会抛出：

useHref() may be used only in the context of a <Router> component.

源码中的 TODO 注释还提示了该错误的一个常见成因：应用里同时加载了两份不同版本的 react-router（见 hooks.tsx），导致 context 无法匹配。

2. 借助 useResolvedPath 完成相对解析

useHref 并不亲自做解析，而是委托给 useResolvedPath。useResolvedPath 读取当前 RouteContext 中的 matches，通过 getResolveToMatches(matches) 把匹配链换算成可供解析的路径名数组：

• 在计算时先由 getPathContributingMatches 过滤掉"不贡献路径"的匹配（如 index 路由、无 path 的布局路由），详见 utils.ts；
• 对于叶子匹配使用完整 pathname（这样 to="." 时能带上 splat 段的值），中间匹配则使用 pathnameBase，见 utils.ts。

随后在 useMemo 中调用核心算法 resolveTo(to, routePathnames, locationPathname, relative === "path")（utils.ts），依赖为 [to, routePathnamesJson, locationPathname, relative]，因此解析结果会被 React 记忆化，仅在相关值变化时重算。

3. 拼接 basename

解析出的 pathname 是相对应用的路径，若应用设置了 basename（即 NavigationContext.basename !== "/"），则在生成 href 前把 basename 前置拼接。一个值得注意的细节：若解析结果是根路径 "/"，则直接使用裸 basename 而不补尾斜杠，把根链接尾斜杠的最终控制权交给 basename 本身（见 hooks.tsx）。这段代码在 <Link> 组件处理 mask 时也被以"内联版本"复制使用，逻辑完全一致（见 dom/lib.tsx）。

4. 交给 navigator.createHref 序列化

最后一步调用 NavigationContext.navigator.createHref({ pathname, search, hash })。不同的 history 实现了各自的 createHref：

• 浏览器环境（createBrowserHistory）与内存环境（createMemoryHistory）的 createHref 都是：字符串直接原样返回，对象则经 createPath 拼回字符串（见 history.ts 与 history.ts）。

由此可见，整个链路可概括为：Router 上下文校验 → useResolvedPath 相对解析 → basename 前置拼接 → navigator 序列化。useHref 自身是纯函数式的"转发 + 拼装"，真正的路径算法在 resolveTo 中。

route 相对 vs path 相对：两种相对解析模式

relative 参数是 useHref 语义中最容易踩坑的部分。默认 "route" 模式下，前导 .. 的含义是"上溯一级路由"，其计算逻辑在 resolveTo 源码 中可清晰看到：

if (!isPathRelative && toPathname.startsWith("..")) {
  let toSegments = toPathname.split("/");

  while (toSegments[0] === "..") {
    toSegments.shift();
    routePathnameIndex -= 1; // 每消费一个 ".." 就沿路由匹配链上溯一级
  }

  to.pathname = toSegments.join("/");
}

from = routePathnameIndex >= 0 ? routePathnames[routePathnameIndex] : "/";

也就是说，.. 消耗的是路由匹配层级索引，而非 URL 中"物理"的 ..。差异在 useHref 的同名测试文件中体现得最直观（见 useHref-test.tsx）。下面用嵌套路由场景举例：

• 向子路由链接：URL 为 /courses 时 useHref("advanced-react") 返回 /courses/advanced-react；
• 向兄弟路由链接：useHref("../about") 返回 /about；
• 向父路由链接：URL 为 /courses/advanced-react 时 useHref("..") 返回 /courses；
• 绝对路径：useHref("/users") 直接返回 /users（与当前路由无关）。

一个非常反直觉但符合规范的行为是：即使 URL 中出现比路径更多的 .. 段也不越界。测试用例中，位于 /courses/react-fundamentals 的组件执行 useHref("../../../courses") 会安全收敛为 /courses；而 useHref("../../..") 则在无法继续上溯时返回根路径 /（见 useHref-test.tsx）。这是"上溯路由树"与"上溯 URL"两种世界观的分水岭。

何时切换到 relative="path"

当你希望 .. 严格按 URL 路径段回溯——即行为接近原生 <a href>——时应显式传入 { relative: "path" }。这与 useHref.md 中"Set to 'path' to make relative routing operate against path segments"的说明一致。在需要把路径当作纯字符串段处理、而非依赖路由嵌套结构时（例如渲染某个文件型深层链接），这是更可控的选项。

尾部斜杠的处理细节

测试覆盖还揭示了对尾部斜杠的精细处理。resolveTo 在解析完成后有一段收尾逻辑（见 utils.ts）：解析后的 Path 会被"校正"以保留 to 中显式书写的尾部斜杠；此外，若 to 为空或 "." 且当前 locationPathname 以 / 结尾，也会保留当前位置的尾部斜杠。对应到测试中的具体断言：

场景	代码	结果
URL 尾斜杠，目标无尾斜杠	initialEntries: ["/courses/"] + to="advanced-react"	/courses/advanced-react（不继承 URL 尾斜杠）
to 显式带尾斜杠	to="advanced-react/"	/courses/advanced-react/（保留显式尾斜杠）
向兄弟路由带尾斜杠	to="../about/"	/about/
to=".."，URL /courses/advanced-react/	向父路由	/courses（不带尾斜杠）
to="../"	向父路由且显式斜杠	/courses/

这些用例都来自 useHref-test.tsx，可作为边界行为的可验证基准。总结规律：尾斜杠由 to 显式写法决定，不被当前 URL 隐式传播。

在真实组件中的落地：Link / NavLink / useLinkClickHandler

useHref 在实际代码库中并非仅供手写调用，它是 <Link> 组件的基石。在 dom/lib.tsx 中可以看到 Link 的实现：

// Rendered into <a href> for relative URLs
let href = useHref(to, { relative });
let location = useLocation();

Link 把 to 和透传的 relative 交给 useHref 得到真实的 href 字符串，再把它渲染进 <a href>。也就是说，你在 <Link to="some/where" relative="path"> 上配置的每一次相对行为，底层都是 useHref 在工作。同理，NavLink 也依赖 useHref 得到 href 后进行激活态匹配，而 useLinkClickHandler 在 Link 的点击事件侧完成导航。值得一提的是，当 Link 使用 mask 特性时，由于解析基准变成了"被遮罩的 location"而非当前 location，Link 无法直接复用 useHref，而是在 dom/lib.tsx 中内联复刻了相同的 basename 拼接 + navigator.createHref 逻辑。

如果你的需求只是"拿到这个链接地址去做渲染之外的事"，可以像 useLinkClickHandler 一样直接调用 useHref；需要预取、悬停高亮等能力则交给 Link / NavLink 组件本身，内部都已处理好。

basename 场景：子路径部署下 href 的正确性

在生产部署到 /app 这类子路径、或为声明式路由设置 <BrowserRouter basename="/app"> 时，useHref 会在第三步把 basename 拼接到解析结果前。可以推断其返回规律为：

• 非根路由：useHref("some/where") 在 basename 为 /app 时返回 /app/some/where；
• 根链接（解析结果为 /）：直接返回 /app（不带多余尾斜杠），实现细节见 hooks.tsx。

正因如此，只要应用的所有链接都经 Link / useHref 生成，子路径部署时无需手工维护 URL 前缀。这也是文档将 basename 相关状态保存在 NavigationContext（含 basename 与 navigator.createHref，见 context.ts）的原因——它与 Router 实例一起提供，useHref 从该 context 同时取到 basename 与序列化函数。

使用注意事项

1. 必须在 Router 上下文中使用：脱离 <Router> 渲染会触发 invariant 报错。这也意味着基于 RouterProvider 的 data / framework 应用中，只要组件处于路由树内即可安全调用。
2. 返回值是字符串：需要解析后的 pathname/search/hash 对象时，应改用它俩的"同门兄弟" useResolvedPath；两者共享同一套 resolveTo 相对解析逻辑。
3. to 不含协议外链：useHref 面向站内路由地址。若需跳转绝对外部 URL（如 https:// 开头），在 Link 场景下会被 ABSOLUTE_URL_REGEX 拦截后按外部链接处理，不进入 useHref 路径。
4. 记忆化缓存：解析在 useMemo 中完成，to、当前匹配链、location pathname 与 relative 任一变化才会重新计算，高频渲染下开销可控。

想验证自己理解是否正确，可直接运行仓库中现成的 useHref 专项测试，其中覆盖了子路由、兄弟路由、父路由、绝对路由、尾斜杠、超量 .. 等全部典型分支。