用途
本技能面向使用 TanStack Router 的开发者与 AI 代理，讲解如何正确利用其“完全类型推断”机制，避免破坏推断链的写法。Params、search params、context 与 loader 数据都会沿路由树自动流转，因此绝大多数场景无需手动标注类型。
主要能力
- Register 模块声明：整个应用唯一必须的类型注解。在创建 router 后通过
declare module '@tanstack/react-router'注册Register接口，之后全局的Link、useNavigate、useSearch、useParams才具备完整类型。 - 类型自动流转：路由钩子（
Route.useParams、Route.useSearch、Route.useLoaderData）与 context 均自动推断，无需注解。 - from 收窄：在钩子与
Link上使用from，将类型从“所有路由的联合”收窄到具体路由，提升 TypeScript 检查速度与精度。 - strict: false：用于跨多个路由复用的共享组件，返回所有路由 search params 的联合。
- getRouteApi：在代码分割（lazy）文件中替代直接导入 Route，避免把路由配置拉入懒加载 chunk。
- TypeScript 性能优化：大型路由树使用对象语法
addChildren；避免 loader 返回未被消费的复杂推断类型；用as const satisfies替代LinkProps变量类型。 - 类型工具：
ValidateLinkOptions、ValidateNavigateOptions、ValidateRedirectOptions用于自定义泛型组件，保持调用点收窄且函数体无需断言。 - 渲染优化：
select细粒度选择器与 structural sharing（仅适用于 JSON 兼容数据）。
使用方式
文档以代码示例展示各写法。核心原则是：不要对已推断的值使用 as Type、显式泛型参数、satisfies 于钩子返回值或类型注解。唯一例外是 Register 声明。跨路由共享组件用 strict: false，代码分割文件用 getRouteApi，自定义组件用 Validate* 类型工具配合泛型重载。
适用场景
适用于所有使用 TanStack Router 的 React 项目，尤其是路由数量多、需要保持类型安全与 TypeScript 检查性能的场景，以及需要为 AI 代理提供正确编码约束的场景。
限制与常见错误
- 禁止对推断值添加类型注解或断言，会掩盖真实类型错误并破坏推断链。
- 不要将 TanStack Router 与 Next.js 或 React Router 混淆：没有
getServerSideProps、没有来自 react-router-dom 的useSearchParams()或useLoaderData()。 - 不要使用未收窄的
LinkProps类型，它是巨大的联合类型，会导致严重的 TS 变慢。 - 不要遗漏 router 类型注册，否则所有路径都是无类型字符串。
- 若构建错误提及 react-router-dom、next/、pages/_app 或重复的 / 路由，应修正导入而非用类型断言掩盖。
- structural sharing 仅适用于 JSON 兼容数据，返回类实例会报错。
文档还提示参见 router-core（Register 设置）、router-core/navigation（from 收窄）、router-core/code-splitting（getRouteApi）。