TanStack RouterRouter 核心 API 全解——从路由树创建、createRouter 配置到类型体系【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router本文以 TanStack Router 官方 API 参考docs/router/api/router.md为主体系统梳理tanstack/react-router及其同构的solid-router、vue-router包中 Router 层的全部 API17 个函数、11 个组件、18 个 Hooks、24 个核心类型与 7 个已弃用 API。读完后你将能够独立完成路由树的搭建、createRouter的完整配置、导航/预加载/错误处理等运行时操作并理解每个 API 在 packages/router-core 中的实现落点。一、API 全景Router 模块由什么组成Router API 总览页 将整套 API 划分为五类。它们共同构成一个客户端优先、但同样具备服务端能力的路由层底层由框架无关的 router-core 包 承载核心逻辑路由匹配、位置解析、加载生命周期等各框架包如 packages/react-router/src/index.tsx在此基础上提供 React 绑定。分类数量代表 API函数17createRouter、createRoute、getRouteApi、redirect、defer组件11Link、Outlet、Await、Navigate、CatchBoundaryHooks18useNavigate、useLoaderData、useParams、useRouterState类型24RouterOptions、RouterState、RouteOptions、ToOptions⚠️ 已弃用7Route类、Router类、RootRoute类等见第五节函数 API 清单路由树构建createFileRoute、createLazyFileRoute、createRootRoute、createRootRouteWithContext、createRoute、createLazyRoute运行时创建createRouter导航与控制流redirect、notFound、isRedirect、isNotFound、lazyRouteComponent路由掩码createRouteMask搜索参数工具retainSearchParams、stripSearchParams路由 API 绑定getRouteApi异步数据defer组件 API 清单Link类型化链接、Outlet嵌套出口、Await消费defer的 Promise、Navigate声明式重定向、MatchRoute按目标渲染任意路由、ClientOnly仅客户端渲染、ErrorComponent、NotFoundComponent、CatchBoundary与CatchNotFound边界捕获、DefaultGlobalNotFound全局 404 兜底。Hooks 清单useAwaited、useBlocker、useCanGoBack、useChildMatches、useLinkProps、useLoaderData、useLoaderDeps、useLocation、useMatch、useMatchRoute、useMatches、useNavigate、useParentMatches、useParams、useRouteContext、useRouter、useRouterState、useSearch。二、路由树构建 APIcreateRoute 与文件路由2.1 createRoute 与 createRootRoutecreateRoute 文档 定义了路由实例的创建方式它接收一个RouteOptions对象并返回一个Route实例。路由实例被传入根路由的children最终组成路由树再交给createRouter。文档给出的标准示例import { createRoute } from tanstack/react-router import { rootRoute } from ./__root const Route createRoute({ getParentRoute: () rootRoute, path: /, loader: () { return Hello World }, component: IndexComponent, }) function IndexComponent() { const data Route.useLoaderData() return div{data}/div }注意Route.useLoaderData()这种静态绑定的用法路由对象本身就是该路由的 API 入口。而在文件路由场景下getRouteApi见 2.3是不持有路由对象引用时的等价手段。createRootRoute用于创建路由树的根节点createRootRouteWithContext则是它的带上下文变体——当根路由声明了上下文类型时createRouter必须提供对应的context见第三节context属性。2.2 createFileRoute / createLazyFileRoute文件路由是 TanStack Router 的默认工作流路由由文件系统约定生成tanstack/router-pluginpackages/router-plugin在构建期产出routeTree.gen文件其中的Route对象由生成器注入id与类型。createFileRoute 文档 中的典型用法import { createFileRoute } from tanstack/react-router export const Route createFileRoute(/posts)({ loader: () fetchPosts(), component: PostsComponent, })createLazyFileRoute文档与createLazyRoute文档是懒加载变体路由的组件与加载逻辑通过lazyRouteComponent文档包裹实现按路由拆分 JS chunk。2.3 getRouteApi类型安全的全局路由 APIgetRouteApi 文档 说明它返回useParams、useSearch、useRouteContext、useNavigate、useLoaderData、useLoaderDeps这批常用 Hook 的类型安全预绑定版本——绑定到具体路由 ID 与注册的路由类型上无需从组件作用域内导入路由对象import { getRouteApi } from tanstack/react-router const routeApi getRouteApi(/posts) export function PostsPage() { const posts routeApi.useLoaderData() // ... }在文件路由项目中由于routeTree.gen由插件生成、id类型已知getRouteApi(/posts)的字符串字面量参数与返回值都受到完整的类型约束——这正是fully type-safe主张在 API 层的直接体现。三、createRouter 与 RouterOptions配置路由器3.1 createRouter 函数createRouter 文档 定义该函数接收一个RouterOptions对象必填返回一个Router实例。最小可运行示例import { createRouter, RouterProvider } from tanstack/react-router import { routeTree } from ./routeTree.gen const router createRouter({ routeTree, defaultPreload: intent, }) export default function App() { return RouterProvider router{router} / }在 router-core 中路由实例的构建与状态管理集中在 Router 核心实现入口导出见 packages/router-core/src/index.tsReact 侧的挂载则通过 RouterProvider 实现 完成——RouterProvider是createRouter返回实例与 React 渲染树之间的桥接。3.2 RouterOptions 核心属性节选与说明RouterOptions 文档 完整列举了所有配置项。以下按用途分组给出类型、默认值与影响要点路由树与历史routeTree必填AnyRoute路由树本身。history可选RouterHistory未提供时内部新建一个createBrowserHistory实例历史管理的实现位于 packages/history 包。basepath可选默认/整个路由器的挂载子路径适合把路由实例挂到子路径下。origin可选URL 解析使用的 origin。默认取浏览器 origin服务端或匿名 origin 下为http://localhost。文档要求传入规范化 origin如https://example.com不带路径与尾斜杠若手头是完整 URL可用new URL(url).origin归一化后再传入。caseSensitive可选默认false为true时所有路由按大小写敏感匹配。trailingSlash可选默认neveralways补尾斜杠、never移除、preserve不修改。搜索参数解析与严格模式stringifySearch/parseSearch可选自定义搜索参数序列化/反序列化函数默认分别为defaultStringifySearch与defaultParseSearch。search.strict可选默认false控制任何validateSearch未声明的未知搜索参数的处理。false保留true丢弃。pathParamsAllowedCharacters可选Array; | : | | | | | $ | ,声明哪些 URI 字符允许出现在 path 参数中而不被encodeURIComponent转义。预加载与缓存defaultPreload可选默认falsefalse表示不做任何预加载intent在用户悬停链接或触发touchstart时预加载viewport在链接进入视口时预加载render在链接渲染进 DOM 时立即预加载。defaultPreloadDelay可选默认50intent 悬停/视口预加载前的延迟毫秒数touch intent 立即预加载。defaultStaleTime默认0、defaultPreloadStaleTime默认30_000ms、defaultPreloadGcTime与defaultGcTime均默认 5 分钟控制 loader 数据新鲜度与预加载/缓存条目的回收时机。defaultStaleReloadMode可选默认background过期 loader 数据的重新验证方式。background保持 stale-while-revalidate 行为blocking则等待过期的 loader 重载完成后才让导航 resolve。组件与等待态兜底defaultComponent默认Outlet路由未提供component时的默认组件。defaultErrorComponent默认ErrorComponent、defaultNotFoundComponent默认NotFound错误与 404 的默认渲染。defaultPendingComponent、defaultPendingMs默认1000、defaultPendingMinMs默认500pending 组件及其显示/最短展示时间。defaultOnCatch可选(error, errorInfo) voidRouter 内部 ErrorBoundary 捕获错误的默认处理器。disableGlobalCatchBoundary可选默认falsetrue时禁用包裹所有路由匹配的兜底捕获边界让未处理错误冒泡到浏览器顶层错误处理器——文档指出这主要用于测试工具、错误上报服务与调试场景。安全protocolAllowlistprotocolAllowlist可选默认DEFAULT_PROTOCOL_ALLOWLIST允许出现在链接、重定向与导航中的 URL 协议数组默认覆盖 Web 导航http:、https:与常见浏览器安全动作mailto:、tel:。不在白名单内的绝对 URL 会被拒绝用于防御 XSS 类风险。文档强调该检查横跨Link to...、navigate({ to/href })、redirect({ to/href })三类导航 API条目必须匹配URL.protocol格式小写带尾冒号配置成blob不带:将无法放行blob:链接。import { createRouter, DEFAULT_PROTOCOL_ALLOWLIST, } from tanstack/react-router // 使用自定义白名单替换默认值 const router createRouter({ routeTree, protocolAllowlist: [https:, mailto:], }) // 或在默认白名单基础上扩展 const router createRouter({ routeTree, protocolAllowlist: [...DEFAULT_PROTOCOL_ALLOWLIST, ftp:], })导航行为defaultViewTransition可选true时导航通过document.startViewTransition()执行传ViewTransitionOptions对象时可附带types数组走startViewTransition({ update, types })浏览器不支持 types 时回退为普通 view transition浏览器完全不支持该 API 时此选项被忽略。defaultHashScrollIntoView可选默认true位置写入历史后是否将 id 与 hash 匹配的元素滚动到视口内传对象则作为scrollIntoView的选项。rewrite可选LocationRewrite在浏览器 URL 与路由器内部 URL 之间做双向转换详见 3.3。context可选若根路由用createRootRouteWithContext()创建则必填注入给整棵路由树的根上下文避免逐路由提供。dehydrate/hydrate可选SSR 脱水/注水时由用户扩展的序列化钩子返回值会并入路由器的脱水状态。404 与 URL 整形notFoundMode可选默认fuzzyroot | fuzzy控制找不到匹配路由时的行为。notFoundRoute已弃用整棵路由树的默认 404 路由可被各分支根路由的选项覆盖。defaultStructuralSharing可选默认false为细粒度选择器默认启用结构化共享。defaultRemountDeps可选(opts) any依据routeId、search、params、loaderDeps计算组件重挂载依赖返回值需 JSON 可序列化返回值得变化时组件重挂载默认导航后保持激活的组件不重挂载。例如remountDeps: ({ params }) params可让所有路由组件在params变化时重挂载。3.3 URL Rewritesrewrite 配置详解rewrite的类型形状引自 RouterOptions 文档type LocationRewrite { input?: LocationRewriteFunction output?: LocationRewriteFunction } type LocationRewriteFunction (opts: { url: URL }) undefined | string | URLinput路由器解释 URL 之前的转换浏览器 → 路由器output写入浏览器历史之前的转换路由器 → 浏览器。文档中的 i18n 前缀示例import { createRouter } from tanstack/react-router const router createRouter({ routeTree, rewrite: { input: ({ url }) { // Strip locale prefix: /en/about → /about if (url.pathname.startsWith(/en)) { url.pathname url.pathname.replace(/^\/en/, ) || / } return url }, output: ({ url }) { // Add locale prefix: /about → /en/about url.pathname /en${url.pathname / ? : url.pathname} return url }, }, })文档特别说明当basepath与rewrite同时配置时二者自动组合——input 阶段 basepath 剥离最先执行output 阶段 basepath 回填最后执行。这一机制在 router-core 中的独立实现见 rewrite 模块。3.4 Wrap / InnerWrap渲染包装层Wrap可选包裹整个路由器的组件只应使用不产生 DOM 的 Provider 类组件否则会引发 hydration 错误const router createRouter({ Wrap: ({ children }) { return MyContext.Provider value{myContext}{children}/MyContext }, })InnerWrap可选包裹路由器内部内容的组件与Wrap的关键区别是它可以访问路由器上下文与 Hookconst router createRouter({ InnerWrap: ({ children }) { const routerState useRouterState() return ( MyContext.Provider value{myContext} {children} /MyContext ) }, })同样地两者都只应承载 Provider 一类不渲染 DOM 的组件。四、Router 实例方法运行时能力Router 类型文档 描述了实例的全部成员。核心提醒router.state永远是最新的但不是响应式的——在组件里读router.state不会触发重渲染响应式读取必须使用useRouterState。成员签名要点说明.update(newOptions: RouterOptions) void用新选项更新路由实例stateRouterState当前状态非响应式.subscribe(eventType, fn) () void订阅 RouterEvent返回退订函数.matchRoutes(pathname, search?, opts?) RouteMatch[]匹配路径与搜索参数throwOnError: true时匹配错误会抛出.buildLocation(opts: BuildNextOptions) ParsedLocation构建待导航的位置对象.commitLocation(location { replace?, resetScroll?, hashScrollIntoView?, ignoreBlocker? }) Promisevoid将位置提交到浏览器历史.navigate(options: NavigateOptions) Promisevoid导航到新位置.invalidate(opts?: { filter?, sync?, forcePending? }) Promisevoid失效选中的路由匹配代际并重跑加载生命周期.clearCache(opts?: { filter? }) void清除缓存的路由匹配与活动预加载.load(opts?: { sync? }) Promisevoid加载当前所有匹配SSR 常用.preloadRoute(opts: NavigateOptions) PromiseRouteMatch[] \| undefined预加载目标匹配.loadRouteChunk(route: AnyRoute) Promisevoid加载路由的 JS chunk.matchRoute(dest: ToOptions, matchOpts?) RouteMatch[params] \| false匹配并返回参数.dehydrate/.hydrate() DehydratedRouter/(dehydrated) voidSSR 状态序列化/反序列化几个值得展开的要点buildLocation的 updater 语义params、search、hash、state均可传true沿用当前值或传 updater 函数以当前值为入参、返回新值mask字段内嵌完整BuildNextOptions并额外支持unmaskOnReload。commitLocation默认行为replace默认false用history.pushresetScroll默认true提交后滚动复位到 0,0hashScrollIntoView默认trueignoreBlocker默认false。.invalidate的语义边界不传filter时失效所有已提交、缓存与在途的匹配代际传filter时它作用于同一集合选中一代即失效同一 match ID 的所有代际。失效会重跑beforeLoad可复用的 loader 数据被标记为过期后走正常加载协议而 match ID 不变时路由级context保持可复用。sync: true使返回的 Promise 在过期加载完成后才 resolveforcePending: true让已有成功数据的路由也进入正常 pending 协议。.load与staleTime文档明确警告router.load()尊重route.staleTime——新鲜的匹配保持新鲜过期匹配会被重新验证需要无视新鲜度强制重载时应改用router.invalidate()。其最常见用途是 SSR 场景在流式渲染客户端之前确保当前路由的关键数据全部就绪。.preloadRoute的推测性活动预加载是推测性的不会成为当前呈现的匹配成功的 loader 数据可进入内存缓存新鲜度遵循preloadStaleTime闲置且超过preloadGcTime后可在后续缓存对账中被回收。每个预加载与导航各自执行beforeLoad链后续 lane 可复用已结算的 loader 数据或并入进行中的 loader 工作但从不复用beforeLoad上下文或已结算的 redirect/error/not-found 结果。该方法在服务端路由实例上同样可用且不影响请求当前的位置与呈现匹配。五、导航、控制流与搜索参数工具函数5.1 redirect 与 notFoundredirect在 loader/beforeLoad中抛出以触发类型安全重定向isRedirect是其守卫函数。notFound抛出 404 语义的错误isNotFound对应判断。这四个函数在 router-core 中分别对应 redirect 实现 与 not-found 实现。5.2 retainSearchParams 与 stripSearchParamsretainSearchParams与stripSearchParams是searchupdater 的辅助前者只替换指定键、保留其余搜索参数后者剔除指定键、保留其余。它们让改一个参数而不打乱 URL 里其它参数成为一行代码的事。5.3 defer 与 流式渲染defer在 loader 中返回一组延迟 Promise配套的Await组件与useAwaitedHook 负责消费它们实现首屏关键数据先渲染、非关键数据流式补全。defer的运行时支持位于 packages/router-core/src/defer.ts服务端流式渲染的入口在 router-core 的 ssr 目录。六、路由掩码createRouteMaskcreateRouteMask 文档 定义该函数创建一个RouteMask配置对象供RouterOptions.routeMasks使用。路由掩码指以与配置匹配不同的路径来显示某条路由——典型场景是弹窗用户看到的是/photos/$photoId/modal但把链接分享出去或刷新后落地的是弹窗内容本身而非弹窗上下文。import { createRouteMask, createRouter } from tanstack/react-router const photoModalToPhotoMask createRouteMask({ routeTree, from: /photos/$photoId/modal, to: /photos/$photoId, params: true, }) const router createRouter({ routeTree, routeMasks: [photoModalToPhotoMask], })与掩码配合的两个路由器级选项routeMasks掩码数组与unmaskOnReload默认falsetrue时页面刷新默认解除掩码可在单个 mask 或单次导航的NavigateOptions.mask.unmaskOnReload上覆盖。七、类型体系总览页 列出的 24 个类型是整套 API 的类型契约按职责可分为四组路由器契约Router、RouterOptions、RouterState、RouterEvents、Register模块级类型注册入口。路由与匹配Route、RouteOptions、RouteApi、RouteMatch、RouteMask、MatchRouteOptions、UseMatchRouteOptions、AsyncRouteComponent。位置与历史ParsedLocation、HistoryState、ParsedHistoryState。导航与错误ToOptions、ToMaskOptions、NavigateOptions、LinkOptions/LinkOptions/LinkProps/ActiveLinkOptions、ViewTransitionOptions、Redirect、NotFoundError。这些类型在源码层面的公共入口是 router-core 的 typePrimitives 模块 与总 index 导出框架包如 packages/react-router/src/index.tsx会将其连同框架绑定一起再导出。八、已弃用 API 与迁移方向总览页 标注了 7 个 ⚠️ Deprecated 条目FileRoute类、Route类、Router类、RouteApi类、RootRoute类、NotFoundRoute类 与rootRouteWithContext函数文档。从文档结构可以确认当前版本的 API 设计已全部转向函数式类被createFileRoute/createRoute/createRootRoute/createRootRouteWithContext等工厂函数取代routeRouteWithContext由createRootRouteWithContext取代。新代码应直接采用函数式 API避免触碰上述类。九、API 与实现的对应关系API文档源码落点router-core 为框架无关核心createRouter/ Router 实例createRouterFunction.mdpackages/router-core/src/router.ts、packages/router-core/src/root.tscreateRoute/ 路由实例createRouteFunction.mdpackages/router-core/src/route.ts文件路由React 绑定createFileRouteFunction.mdpackages/react-router/src/fileRoute.tsredirect/notFoundredirectFunction.mdpackages/router-core/src/redirect.ts、packages/router-core/src/not-found.tsrewriteRouterOptionsType.mdpackages/router-core/src/rewrite.tsdeferdeferFunction.mdpackages/router-core/src/defer.tsLinklinkComponent.mdpackages/router-core/src/link.ts、packages/react-router/src/link.tsxuseNavigate/useRouterStateuseNavigateHook.mdpackages/router-core/src/useNavigate.ts、packages/react-router/src/useRouterState.tsx从源码结构看router-core承担了匹配matches 模块、位置解析location 模块、搜索参数中间件searchMiddleware 模块、结构化共享structuralSharing 模块等横切能力各框架包只做渲染与响应式绑定——这解释了为何同一套 API 参考可以覆盖 React、Solid、Vue 三种前端。十、小结路由树由createRootRoute/createRoute或文件路由下的createFileRoute/createLazyFileRoute构建最终交给createRouter({ routeTree, ... })装配成可运行的路由器RouterProvider负责将其挂载进应用RouterOptions是全部行为的配置面预加载策略defaultPreload/defaultPreloadDelay、缓存新鲜度staleTime系列、404 策略notFoundMode、安全边界protocolAllowlist、URL 整形basepath/rewrite/trailingSlash与 SSR 序列化dehydrate/hydrate都从这里配置运行时导航能力集中在 Router 实例方法navigate/buildLocation/commitLocation处理位置流转invalidate/clearCache/preloadRoute/load处理数据与缓存生命周期subscribe暴露完整事件流getRouteApi提供了不依赖组件作用域的类型安全 Hook 绑定与retainSearchParams/stripSearchParams、defer/Await、createRouteMask一起覆盖了搜索参数、流式数据与弹窗路由三类高频实战场景类式 API 已全部弃用编写新代码时直接使用第八节之前的函数式 API 即可。【免费下载链接】router A client-first, server-capable, fully type-safe router and full-stack framework for the web (React and more).项目地址: https://gitcode.com/GitHub_Trending/ro/router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考