TanStack Router 与路由

• 路由级 code splitting 与按需加载
• preload 提前加载路由代码
• 与 Suspense 的配合

TanStack Router 支持 route.lazy 或基于 Route.lazy 的懒加载，把路由的组件与 loader 拆成独立 chunk，导航到该路由时才加载，降低首屏体积。route.preload 指定在链接 hover/进入视口等时机预先加载该路由 chunk，让用户点击时模块已就绪实现即时导航。配合 Suspense 挂起未加载的 chunk。工程价值是大型应用按路由拆分，首屏只加载当前路由代码。

lazy 是"用到才加载"，preload 是"提前加载将要用的"，两者结合兼顾体积与导航速度。

• 路由局部状态与全局状态的分工
• 外部状态库与 Router 的集成
• 与 search 参数状态的取舍

工程上把"可分享、可恢复"的状态（筛选、分页）放 Router 的 search params，把"会话级、跨路由全局"的状态（用户信息、主题、购物车）放 Zustand/Jotai。TanStack Router 与外部状态库协作时，可通过 routeContext 注入 store，或在 loader/beforeLoad 中读取 store 以决定重定向。二者不冲突而是互补：Router 管 URL 可寻址状态，状态库管内存全局状态。

关键原则是"该进 URL 的进 URL，该进 store 的进 store"，避免把可分享状态塞进全局 store 导致刷新丢失。

• 全链路类型安全（路径、参数、search、loader 数据）
• 团队规范的约束与收益
• 代码组织方式（文件路由 vs 代码路由）

type-safe 路由让 Link 的 to、params、search、loader 返回的数据类型全部在编译期推导，拼错路径或传错参数会直接报类型错误。这对团队规范是强约束：新人难以写出路径字符串错误，破坏性变更在编译期暴露。取舍是：需要维护由 tsr 生成的路由类型（routeTree.gen.ts），增加少量学习成本与生成步骤；但收益是跨团队重构安全性与代码可导航性大幅提升。

类型安全把"约定的正确性"从运行时挪到编译期，是团队协作中减少低级错误的关键，代价是代码生成与类型约束的学习成本。

• File-based routing 的约定组织
• tsr generate 自动生成路由树类型
• 与手动 createRoute 的对比

文件路由把路由定义映射到文件系统（routes/ 目录），约定化组织组件与 loader，目录结构即路由结构。tsr generate 扫描文件生成 routeTree.gen.ts 与类型，IDE 自动补全 Link 路径。取舍：文件路由适合约定优先、团队规范统一的场景，代码组织直观；手动 createRoute 更灵活但需维护路由树。现代建议是文件路由 + 代码生成，兼顾可维护性与类型安全。

文件路由用"文件系统约定"替代"手工注册"，降低维护成本；代码生成把类型安全自动带到每个路由。

• 强类型表单状态
• 与 zod 校验器集成
• 字段级订阅与类型推导

TanStack Form 的表单状态是强类型的，字段名、值类型在编译期推导，配合 zod 校验器可让 schema 同时驱动类型与校验逻辑。它的字段值通过 useStore(field) 订阅，配合 form.state 细粒度更新，避免整表重渲染。工程价值：类型安全减少表单字段书写错误，zod resolver 单一来源保证类型与校验一致，适合大型复杂表单。

"typed state + zod schema"让表单的字段类型、默认值、校验规则由同一 schema 驱动，减少重复与不一致。

• headless 表格逻辑与 UI 分离
• 行模型与排序模型的组合
• 大型表格的表现与虚拟化

TanStack Table v8 是 headless 库，getCoreRowModel 提供基础行数据处理，getSortedRowModel 提供排序逻辑，二者作为 plugin 组合传入，生成 table 实例供 UI 消费。UI（thead/tbody）完全由开发者用任何组件库渲染，逻辑与表现彻底解耦。工程价值：可在排序、筛选、分页、虚拟滚动上自由组合，支持大型表格配合 @tanstack/react-virtual 虚拟化。

headless 模式把"表格逻辑"做成可组合的纯函数模型，UI 自由渲染，是跨组件库复用与定制的基础。

• createServerFn 定义服务端函数
• 客户端调用与类型透传
• 与 loader/action 的集成

createServerFn 在客户端代码中声明一个服务端执行的函数，构建时自动拆分为服务端逻辑与客户端调用器，函数签名与返回类型在两端一致，从而端到端类型安全。客户端调用时通过 RPC 传输参数并返回结果，类型在编译期推导，无需手动写 API 类型或请求代码。它支持在 loader 中、事件处理器中调用，是 Start 全栈能力的核心。

createServerFn 的魔法在于"同一份函数签名同时驱动两端类型"，把 RPC 通信的样板与类型断层消除。

• middleware 的 before/after 生命周期
• 鉴权与上下文注入
• 参数校验与日志串联

Start 的 middleware 支持 before 与 after 阶段，可以串联多个中间件形成责任链。before 阶段可做鉴权（校验 session、注入 user 到 context）、参数校验（zod 校验 input）、日志（记录请求开始）；after 阶段可做响应日志、错误处理。中间件通过 context 传递数据，前后共享，可组合复用。工程价值是把横切关注点（鉴权、日志、校验）从业务代码中抽离，统一治理。

中间件链是"横切关注点"的容器，before 校验/鉴权、after 日志/错误，通过 context 传递累积状态。

• 命令式添加组件源码
• 覆盖本地文件并配置
• 与项目依赖的按需集成

npx shadcn@latest add button 会从 registry 拉取组件源码文件，直接写入项目的 components/ 目录，并自动安装所需依赖、更新 CSS 变量。它不新增运行时的 shadcn 依赖，组件源码归项目所有，可任意修改。工程价值：按需引入避免整体打包体积，源码可定制，与 Tailwind 配置无缝集成，升级也通过重新 add 拉取新版拷贝。

CLI 是"复制源码"哲学的落地工具，把组件以源码形式注入项目，所有权与可定制性归用户。

• 源码拷贝 vs 依赖安装
• 可定制性与所有权
• 避免版本锁定的升级负担

shadcn 不让你 npm install 一个组件库，而是把组件源码复制进项目。价值：组件代码完全属于项目，可深度定制而不受库 API 限制；没有 npm 依赖锁定和版本升级破坏；Tree-shaking 天然最优（只拷贝用到的）；tailwind 配置与 CSS 变量直接融入项目。代价是升级需手动重新拷贝并且团队需自行维护 fork。总体是"可控性优先"的分发哲学。

"Copy-paste"哲学让组件库成为"模板"而非"依赖"，换取最大可定制性与最小体积，把维护成本转移到开发者。

• 乐观更新即时反馈
• onError 回滚
• 缓存一致性

点赞/关注这类高频、低延迟期望的操作，等待网络返回会造成明显卡顿。乐观更新在 mutate 发起时立即更新 UI（如点亮红心），onError 时回滚到之前状态并提示。工程价值：交互感知即时，提升体验；配合 cancelQueries 暂停在途请求避免竞态，onMutate 保存旧值用于回滚。这是现代社交应用的标准做法。

乐观更新的关键是"先改 UI，失败还原"，并处理并发竞态（cancelQueries）与缓存一致性。

• 源码分发 vs 运行时依赖
• 定制方式与样式耦合
• 受控程度与可维护性

传统组件库（Ant Design、MUI）以 npm 依赖引入，内置完整样式与主题系统，通过 tokens 或覆盖机制定制，升级由库版本驱动。shadcn/ui 则把组件源码复制进项目，无运行时依赖，样式用 Tailwind 直接书写，可逐行修改。差异的本质是"控制权归属"：传统库控制权在库作者，定制受 API 限制且升级可能破坏定制；shadcn 控制权在开发者，定制无限制但需自行维护升级与一致性。

选择取决于权衡：传统库省心、开箱即用但定制与升级受限；shadcn 灵活可控但要求团队具备维护能力。

• 按需拷贝源码的分发
• 无运行时打包负担
• 定制与升级的机制

原理是 shadcn 通过 registry 协议提供组件源码，CLI 拉取后写入项目源码目录，作为项目自身代码参与构建。它不提供 npm 包，因此没有版本锁定、peer 依赖冲突或运行时体积；组件与项目 Tailwind 配置天然融合。升级时重新 add 拉取新版本覆盖本地文件（可能产生 diff）。这实质是把"组件库"从"依赖"降维为"开发模板"，让用户拥有全部源码。

模式本质是"模板化分发"，牺牲集中升级换取所有权与可定制性，是 shadcn 生态的基石。

• registry.json 的 schema
• 组件元数据与文件列表
• 分发与按需安装

Registry 协议用 JSON 描述一组组件，每个组件声明其名称、文件列表、依赖、样式依赖（tailwind 配置）、registry 源等。CLI 读取该 JSON，按需拉取指定组件的文件并写入项目。registry.json 的 schema 让组件可被程序化安装，也支持私有 registry 让团队自建组件分发中心。分发的核心是"元数据驱动安装"，使组件像 npm 包一样可被 CLI 添加，但落点是源码而非依赖。

Registry 协议是 shadcn 分发的基础设施，把"组件 + 依赖 + 样式配置"打包成可安装的元数据，是私有组件库的关键。

• Tailwind v4 的 CSS-first 配置
• @theme 定义设计令牌
• shadcn 的 CSS 变量映射

Tailwind v4 推荐 CSS-first 配置，用 @theme 在 CSS 中定义设计令牌（颜色、间距等），生成对应的工具类。shadcn/ui 在 v4 下把语义色（如 --background、--primary）定义为 CSS 变量，再通过 @theme inline 映射到 Tailwind 工具类，使 bg-background、text-primary 等类可用。二者协同让主题令牌既能在 CSS 中维护，又能被工具类消费，同时支持暗黑模式通过变量切换。

@theme 提供"单点定义令牌"，shadcn 把语义色映射到 Tailwind 工具类，实现设计令牌与工具类的统一。

• packages/ui 内部的组件共享
• 源码如何被多项目消费
• 与构建/发布的关系

在 monorepo 中，常用做法是建一个 packages/ui 包，把 shadcn 组件源码放进去，作为内部依赖被多个应用消费。由于组件是基于 Tailwind 的源码，需要处理样式：要么把 Tailwind 配置与 CSS 变量集中,让各应用共享；要么用 Tailwind v4 的 @source 指令让 ui 包内的类被扫描。跨项目复用通过把 ui 包发布为 npm 包或通过 workspace 依赖实现。核心是让"源码 + 样式配置"一起被消费。

复用的关键是把组件源码、Tailwind 配置与设计令牌一起打包或共享，保证样式在消费方正确生成。

• @theme 定义令牌与工具类生成
• @plugin 扩展插件能力
• 与纯 CSS 变量设计系统的对比

@theme 在 CSS 中定义设计令牌并自动生成工具类，@plugin 用于在 CSS 中引入 JS 插件以扩展 Tailwind 能力（如自定义工具）。与纯 CSS 变量设计系统相比，@theme 的差异在于：它不仅是运行时变量，还会在编译期生成对应的工具类，且可参与 Tailwind 的 class 检测与响应式。纯 CSS 变量系统只做运行时替换，无编译期工具类生成。工程边界是：静态令牌用 @theme 享受工具类生成，动态/运行时变量仍用原生 CSS 变量。

@theme 是"编译期 + 运行时"双层的令牌系统，比纯 CSS 变量多了工具类生成与类名集成能力。

• path/search 的类型安全解析
• 与 React Router v7 的对比
• 工程选型考量

TanStack Router 对 path/search 做类型安全的解析，路径参数、search 参数类型由 schema（如 zod）驱动，编译期推导。React Router v7 的 search 也支持 schema 校验但类型集成相对更浅。取舍上：TanStack Router 类型安全与数据流（loader、preload）更紧密，适合重类型安全团队；React Router v7 生态成熟、与 React 生态兼容更广、学习成本低。工程选择取决于团队对类型安全、路由数据流与生态的优先级。

两者理念相近但深度不同：TanStack Router 把类型安全与数据流做到底，React Router v7 更通用、生态更成熟。

• beforeLoad 的鉴权与前置逻辑
• search schema 校验参数
• 校验失败的处理

beforeLoad 在 loader 之前执行，可用于鉴权、读取上下文、校验 search 参数。配合 zod 的 search validator，在 beforeLoad 中解析并校验 search 参数，非法参数可抛错或重定向。loader 则拿到已校验的干净的 search 数据。工程价值：把"参数合法性"与"数据获取"分离，非法访问在进入渲染前就被拦截，保证 loader 输入可信。

beforeLoad 负责前置校验与鉴权，search schema 定义参数形状，二者让 loader 只处理可信输入。

• 编译期推导路径与 search 类型
• 减少运行时错误
• 与 schema 校验的数据一致性

useParams/useSearch 返回的类型由路由定义与 validateSearch 推导，读取 params.id 或 search.q 时类型已明确，无需手写类型断言。大型应用价值：跨组件引用路由参数时类型一致，重构路由定义时引用处自动报错，避免字符串拼写与类型不匹配导致的运行时崩溃。配合 schema 校验，类型与运行时校验双保险，提高数据链路可信度。

类型推断把"参数读取"的类型责任交给编译器，降低手写类型与实际不一致的风险。

• 路由定义到 loader 数据的类型推导
• Link 的目标类型校验
• loader 数据在组件中的类型消费

类型安全路由把路由定义编译为类型，Link 的 to 目标必须是已注册路由，params/search 类型由路由 schema 推导，loader 返回值类型也关联到组件。组件通过 useLoaderData 拿到与 loader 返回一致的强类型数据。结合 loader 模式，形成"路由定义 → 导航 → loader → 组件消费"全链路类型安全，任何一环类型不匹配都会在编译期暴露。

类型安全贯穿导航与数据流，loader 返回类型直达组件使用点，是框架级保障。

• 文件路由组织的直观性
• Route Tree 的生成与查询
• 团队协作与维护

文件路由把路由以文件/目录结构组织，routes/ 目录即路由树，直观可导航。Route Tree 由 tsr generate 自动生成，是路由的静态类型描述，供 Link、useParams 等消费。大型项目价值：目录即文档，新增路由只需加文件；Route Tree 集中提供类型，避免手工维护路由树；代码生成保证路由与文件一致，减少遗漏。适合团队规模大、路由多的场景。

文件路由 + 自动生成 Route Tree 让"路由组织"与"类型安全"自动化，是大型项目可维护性的基础。

• beforeLoad 做鉴权与重定向
• loader 做数据预取
• 二者时序与上下文传递

beforeLoad 在 loader 之前执行，常用于鉴权：检查登录态，未登录则抛 redirect 重定向到登录页，并可通过 context 注入用户信息。loader 在鉴权通过后执行，负责数据预取。二者通过 context 协作：beforeLoad 返回的 context 注入 loader。工程价值是"先鉴权后取数"，避免未授权用户触发数据请求，且鉴权信息可被 loader 复用。

beforeLoad 负责"能不能进"，loader 负责"进后取什么"，时序明确、职责分离。

• 服务端渲染路由
• loader 数据在服务端执行
• streaming 流式输出

TanStack Router 支持 SSR，在服务端用 router 解析请求 URL、执行匹配路由的 loader 预取数据，再渲染 HTML。streaming SSR 允许把 loader 数据与 HTML 分块流式传输，配合 TanStack Query 的 dehydrate 在流式边界注入数据。客户端水合后复用服务端数据。工程价值是首屏数据与渲染同源、减少重复请求，并支持流式提升 TTFB。

SSR 集成让"路由解析 + loader 执行 + 渲染"在服务端完成，streaming 进一步优化首屏体验。

• preload 预取数据
• error boundary 捕获渲染/loader 错误
• route context 提供依赖

preload 在导航前预取目标路由数据，加快进入速度；error boundary 在路由级捕获 loader 或渲染错误，就近展示错误 UI 而非整页崩溃；route context 注入应用级依赖（queryClient、auth 等）供 loader/beforeLoad 使用。三者协同：preload 负责性能、error boundary 负责容错、context 负责依赖注入，共同构成健壮的路由运行环境。

三者分别关注性能、容错与依赖注入，构建完整的路由生命周期保障。

• select 在数据流内转换
• useEffect 同步外部数据的时机
• 避免重复渲染与竞态

select 在校验/缓存层对数据做转换，返回给组件，转换在数据流内、无副作用、可被 memo 优化。useEffect 同步数据是命令式、在渲染后执行，可能触发额外渲染与竞态（如旧响应覆盖新数据）。工程取舍：优先用 select 处理纯派生数据，避免 useEffect 同步；若必须同步外部系统（如非 React 库），用 useEffect 并做好清理与请求取消。原则是"能派生就不同步"。

派生数据应走 select/memo 等声明式路径，useEffect 只在确有副作用时使用，减少多余渲染与竞态。

• useQueries 传数组返回查询数组
• 动态数量时的类型推导
• 生命周期（增删查询）管理

useQueries 接收一个查询配置数组，返回结果数组，可并行执行多个不同 queryKey 的查询。当数组长度动态变化时，返回数组长度随之变化，类型上需注意 combine 与 res 的映射。生命周期管理：新增查询自动发起、删除查询自动清理缓存时机（gcTime 控制），不会因数量变化导致状态错乱。工程上常配合 combine 把结果聚合成单一对象，避免多条渲染。

useQueries 适合"一组动态 id 各自取数"，用 combine 聚合结果，长度变化由库自动管理。

• 可视化缓存与查询状态
• 手动刷新/失效/删除
• 定位问题

TanStack Query DevTools 提供缓存查看器，展示每条查询的 queryKey、状态（pending/success/error/fetching）、数据与更新时间，可手动刷新、失效、删除某条查询，模拟网络断开。工程价值：无须写代码即可观察与操作缓存状态，快速定位"为什么不刷新/数据过期/缓存错乱"等问题，是调试数据层的利器。

DevTools 把内部缓存状态可视化，让开发者能直接操作与观察，提升数据层调试效率。

• 路由类型生成
• Link/params/search 的类型约束
• 与 schema 校验配合

类型安全路由通过 tsr generate 生成 routeTree 类型，Link 的 to 必须匹配已注册路由，params/search 类型由路由 schema（validateSearch）推导，loader 数据类型关联组件。任何不一致在编译期报错。它把"路由字符串约定"升级为"类型系统约束"，配合 schema 校验保证运行时与类型一致，是框架最核心的差异化能力。

类型安全源自"代码生成 + schema 推导"，把路由正确性从运行时提升到编译期。

• 代码路由的显式与灵活
• 文件路由的约定与直观
• 场景选择

createRoute 代码路由在单个文件里显式声明路由、loader、组件，灵活可控、适合动态/复杂路由或小项目；文件路由按目录约定组织，routes/ 即路由树，直观适合大型团队。取舍：代码路由灵活但需维护路由树与类型，文件路由约定化但需代码生成。现代推荐文件路由，但复杂场景可混合。工程选择取决于团队规模与约定偏好。

代码路由重显式与灵活，文件路由重约定与直观，通常按项目规模与协作方式选择。

• 自动生成路由类型
• 与文件路由配合
• CI 与类型安全

tsr generate 扫描 routes/ 目录，自动生成 routeTree.gen.ts 与路由类型，供 Link、useParams、useLoaderData 等消费。它在监听模式（--watch）下随文件变化自动重新生成，也可在 CI 中运行保证类型最新。现代应用是配合文件路由让"路由新增即类型更新"，无需手动维护，同时保证类型安全与代码一致性。

tsr generate 把"路由结构"转成"类型"，是文件路由 + 类型安全的关键自动化环节。

• 两种 notFound 模式的区别
• 就近 vs 根级 404 处理
• 嵌套路由的匹配

notFoundMode 有 'root'（默认）与 'fuzzy' 两种。root 模式：找不到时在根级渲染 notFound 组件；fuzzy 模式：找不到时向上追溯到最近的、能匹配前缀的父路由，在其边界内渲染 notFound。工程应用：fuzzy 更精确，可在嵌套路由的父级显示局部 404（如子页面不存在但在父布局内提示），root 更简单全局。选择取决于嵌套结构与 404 展示粒度。

notFoundMode 决定 404 在路由树的哪一层展示，fuzzy 提供更精细的局部 404。

• 三种 SSR 方案的定位
• TanStack Router + 自建 SSR 与 Start 的差别
• React Router v7 的 SSR 模式

TanStack Router 本身提供 SSR 渲染能力，可被自建服务端框架或 TanStack Start 使用。TanStack Start 是完整全栈框架，内置服务器、server functions、SSR/streaming 集成。React Router v7 提供框架模式（loader、action、SSR）与库模式。取舍：TanStack Start 类型安全与数据流最统一但生态较新；React Router v7 生态成熟、SSR 模式简单；裸 TanStack Router SSR 需自建集成。工程按团队对全栈能力与生态的需求选择。

三者都是 SSR 方案，但集成深度不同：Start 全栈统一、React Router v7 成熟灵活、裸 Router 需自建。

• 拦截导航的条件
• 未保存表单的提示
• 是否放行

useBlocker 可注册一个拦截器，当满足条件（如表单 dirty）时阻止导航或弹出确认。典型场景：用户有未保存表单离开时，useBlocker 触发，提示"是否保存/放弃"，用户确认后放行。工程价值：防止误操作丢失数据，提升表单体验。需要配合条件判断（如 form.isDirty）避免在无改动时也拦截。

useBlocker 是"导航守卫"，在离开前拦截并根据业务条件决定放行或提示。

• useRouter 获取路由实例
• useRouterState 订阅路由状态
• 响应式路由信息

useRouter 返回 router 实例，用于命令式导航（router.navigate）、失效等操作；useRouterState 订阅路由状态（location、matches、isPending 等），返回响应式数据，组件随路由变化重渲染。工程应用：在组件中读取当前路径、导航状态、匹配路由，或驱动 UI（如导航菜单高亮、路由过渡动画）。二者配合实现"操作路由"与"感知路由"。

useRouter 管"操作"，useRouterState 管"订阅"，是组件内与路由交互的入口。

• 向路由注入共享依赖
• loader/beforeLoad 读取
• 跨层级传递

routeContext 在创建 router 时注入应用级依赖（queryClient、auth、i18n 等），所有路由的 loader/beforeLoad 都能通过 context 读取。它实现跨层级的数据共享：父路由注入的 context 可被子路由继承，子路由可覆盖。工程价值：避免用全局变量传递依赖，让 loader 有明确的依赖来源，且可在 loader 中做鉴权、i18n 等横切逻辑。

routeContext 是"路由数据流依赖注入"的机制，让 loader 依赖可注入、可测试、跨层级共享。

• activeOptions 的配置
• 精确匹配 vs 包含匹配
• 导航菜单高亮

Link 的 activeOptions 可配置激活态判断，如 { exact: true } 要求精确匹配路径才激活，{ includeSearch: true } 将 search 纳入匹配。工程实践：导航菜单用 activeOptions 控制当前项高亮，精确匹配用于无子项的顶级菜单，包含匹配用于带子路由的父级菜单。它让激活态判断可配置、符合嵌套路由的高亮需求。

activeOptions 控制 Link 何时视为激活，是导航高亮正确性的关键配置。

• 可视化路由树与匹配
• 查看 loader 数据与状态
• 定位导航问题

Router Devtools 提供路由树可视化、当前匹配路由、loader 数据、search/params 状态的可视化面板，能查看导航状态（isPending）、加载错误等。工程价值：无须 console 即可观察路由匹配、loader 执行与数据流，快速定位"路由没匹配/loader 没执行/数据错误"等问题。

Devtools 把路由内部状态可视化，是调试路由与 loader 数据流的利器。

• Pacer 的三种策略
• 与 React 状态/事件结合
• 性能优化

TanStack Pacer 提供防抖（debounce）、节流（throttle）、速率限制（rate limit）等工具，可在 React 中用于搜索输入、滚动、点击等高频事件。集成方式：用 hook 或 ref 包装回调，在事件中调用，避免每次触发都更新状态或发请求。工程价值：减少高频操作的渲染与请求次数，提升输入与滚动性能，且 Pacing 逻辑可复用、可测试。

Pacer 把"频率控制"抽成可复用工具，与 React 事件结合优化高频交互。

• 只渲染可视区子项
• 动态尺寸与测量
• 与滚动容器配合

TanStack Virtual 通过计算滚动位置，只渲染可视区内的子项，并预留占位高度，实现高效虚拟滚动。它支持动态尺寸（测量真实高度）、横向/纵向滚动、自定义滚动容器。工程价值：对万级列表大幅减少 DOM 节点与渲染开销，保持滚动流畅，是表格、列表、聊天等场景的标配。

虚拟滚动的核心是"只渲染可视窗口内的项"，配合占位与测量保持滚动一致性。

• 状态与渲染解耦
• 框架无关
• 响应式原语驱动

headless 模式把表格状态（排序、筛选、分页、列）与渲染逻辑分离，状态存放在通用响应式原语中，UI 由开发者用任意框架渲染。TanStack Table 的状态是框架无关的，v8 通过 hooks 暴露，v9 甚至可独立于框架。工程价值：跨框架复用、逻辑可测试、UI 完全自定义，是大型复杂表格的基础。

headless 把"数据/状态逻辑"与"UI"解耦，让逻辑可跨框架复用、UI 可自由定制。

• 轻量级 store
• 订阅与更新
• 与框架集成

TanStack Store 是一个框架无关的轻量级状态管理库，提供 store、订阅、transactions 等，API 极小，可被 React/Vue 通过 hook 绑定。它适合局部或共享状态，按需订阅避免多余渲染。工程价值：体积小、无样板、可与任何框架配合，适合作为 Query 等底层状态或简单的全局状态。

Store 主打"轻量 + 框架无关 + 细粒度订阅"，在需要可控状态时避免引入重型状态库。

• Start 基于 Router 的文件路由
• loader 预取与 SSR 融合
• 全栈数据流

TanStack Start 基于 TanStack Router 的文件路由组织路由，loader 在服务端与客户端执行以预取数据。Start 增强 loader：支持服务端执行、配合 createServerFn 取数、SSR 时预取并 dehydrate 传输。协作形成"文件路由定义 → loader 预取 → SSR 数据直出 → 客户端水合复用"的全栈数据流，导航与数据无缝衔接。

Start 把 Router 的路由与 loader 能力提升到全栈，服务端预取 + 客户端复用构成完整数据流。

• Nitro 作为服务端运行时
• preset 适配多平台
• 部署灵活性

TanStack Start 使用 Nitro 作为服务端运行时，Nitro 提供多种部署 preset（node、vercel、netlify、cloudflare、deno 等），一套代码按 preset 部署到不同平台。工程价值：应用逻辑与部署平台解耦，切换平台只需改 preset，无需改动业务代码，提升部署灵活性与可移植性。

Nitro 的 preset 机制让"平台差异"收敛到配置层，一套代码多平台部署。

• 类型安全程度
• 框架耦合度
• 生态成熟度

类型安全：TanStack Start 的端到端类型安全（createServerFn、类型安全路由）最彻底，Next.js/Remix 次之。框架耦合度：Start 与 TanStack 生态深度绑定、较新；Next.js 与 React 深度绑定、生态最成熟；Remix 多框架。生态成熟度：Next.js 最成熟、社区资源最丰富，Remix 次之，Start 较新但增长快。选型权衡：追求极致类型安全与统一数据流选 Start，追求生态成熟与稳定选 Next.js，需要多框架支持选 Remix。

三者的取舍是"类型安全/现代性 vs 生态成熟/稳定性"的权衡，按团队能力与项目需求选择。

• server functions 的 RPC 能力
• RSC 的组件流式渲染
• 边界与互操作

server functions（如 createServerFn）是"客户端可直接调用的服务端函数"，以 RPC 形态提供数据读写与业务逻辑；RSC 是"组件在服务端渲染、序列化到客户端"的范式，侧重渲染而非交互调用。边界：server functions 管数据/操作，RSC 管渲染；互操作：RSC 可在服务端调用 server functions 或共享取数逻辑，client 组件不能直接调 server functions 外的服务端逻辑。二者可结合，但职责不同。

server functions 是"调用服务端"的边界，RSC 是"渲染来自服务端"的边界，角色不同可互补。

• 私有 registry 承载企业组件
• 元数据驱动的按需安装
• 与设计系统集成

企业可自建私有 registry（registry.json），把内部组件、设计令牌、样式配置以元数据形式分发，团队通过 npx shadcn add <component> 从私有源安装。工程价值：组件按需注入源码、可定制、与设计系统令牌统一；分发与团队规范集中；避免 npm 私有包的管理复杂度。它让企业组件库像 shadcn 官方一样"源码分发 + 元数据驱动"。

私有 registry 复用 shadcn 的"源码分发 + 元数据驱动"模式，承载企业组件库与设计系统。

• 在浏览器运行 ONNX 模型
• InferenceSession 创建与推理
• 硬件加速（WebGPU/WebGL/WASM）

ONNX Runtime Web 可在浏览器运行 ONNX 格式的机器学习模型，通过 InferenceSession.create() 加载模型、session.run() 执行推理，支持 WebGPU/WebGL/WebAssembly 后端实现硬件加速。工程价值：模型推理在客户端完成，无需服务端、降低延迟与带宽、保护隐私，适合 OCR、图像分类、NLP 等 AI 应用，是客户端 AI 的核心运行时。

InferenceSession 封装模型加载与推理，配合多后端加速，让浏览器能跑 AI 模型。

• 浏览器内置摘要能力
• 与编程工具链的集成
• 本地 AI 与隐私

Summarizer API 是浏览器内置 AI 能力，可在本地对文本生成摘要。在 AI 编程工具链中，可用于代码/文档/Issue 的自动摘要、生成 commit message、会议纪要提炼等，与本地模型协作无需上传云端。工程价值：低延迟、隐私安全、离线可用，与编辑器/IDE/协作工具集成提升效率。

Summarizer API 提供本地摘要，为编程工具链提供轻量、隐私友好的 AI 能力。

• Rewriter 的文本改写能力
• Chrome Built-in AI 的本地模型
• 与应用的集成

Rewriter API 是 Chrome Built-in AI 的一部分，提供本地文本改写（润色、改写语气、简化等），基于浏览器内置的 Gemini Nano 模型。现代协作：应用调用 Rewriter API 在本地改写文本，无需后端与 API key，支持离线。工程价值：文本改写功能嵌入编辑器、评论、写作助手等，隐私安全、低延迟，是浏览器本地 AI 的先进能力。

Rewriter API 依托 Chrome Built-in AI 本地模型，提供隐私友好的文本改写能力。

• @theme 定义设计令牌
• shadcn 组件类名依赖令牌
• 主题定制

Tailwind v4 用 CSS-first 配置，@theme 在 CSS 中定义设计令牌并生成工具类。shadcn/ui 在 v4 下把语义色定义为 CSS 变量，再通过 @theme inline 映射为工具类（如 --color-primary），组件使用 bg-primary、text-foreground 等类。集成后，主题定制只需改 CSS 变量，组件类名不变，支持暗黑模式与多主题。

CSS-first 配置让令牌定义在 CSS 中，shadcn 通过 @theme 映射类名，实现主题与组件的解耦。

• WebGPU 的 GPU 计算能力
• Compute Pipeline 做通用计算
• 与专用 ML 库（WebNN/TensorFlow.js）的取舍

WebGPU 通过 Compute Pipeline 提供 GPU 通用计算，可自行实现矩阵运算等 ML 内核，灵活但需自行实现算子与优化。专用 ML 库（WebNN、TensorFlow.js、ONNX Runtime WebGPU 后端）封装了算子与推理，开发效率高。取舍：WebGPU Compute 适合深度定制、教学或特殊算子；库方式适合快速部署、性能稳定。工程上通常用库封装，WebGPU 提供底层能力。

WebGPU Compute 是底层能力，ML 库在上层封装，权衡是"灵活性 vs 开发效率"。

• @custom-variant 定义 dark 变体
• class 策略 vs 系统策略
• 手动切换与系统跟随

Tailwind v4 默认 dark 变体跟随 prefers-color-scheme（系统偏好），可用 @custom-variant dark (&:where(.dark, .dark *)) 改为 class 策略（.dark 类控制）。取舍：prefers-color-scheme 自动跟随系统、无需 JS，但无法手动切换；.dark 类可手动切换、支持用户自定义主题，需 JS 管理类名。工程上常采用 class 策略以支持主题切换控件。

取舍是"系统自动 vs 用户手动"：class 策略更灵活支持切换，系统策略更省心。

• Preflight 的浏览器默认样式重置
• Cascade Layers 的层级控制
• 与第三方样式冲突处理

Tailwind 的 Preflight 提供基础样式重置（统一浏览器默认样式），v4 中 Preflight 位于 layer(base)。CSS Cascade Layers（@layer）控制样式优先级层级，Tailwind 用 theme/base/components/utilities 分层，utilities 层最高。工程取舍：用 Layers 让工具类稳定覆盖组件样式，避免特异性冲突；Preflight 保证跨浏览器一致。第三方样式可用 @layer 纳入层级管理。

Preflight 做重置，Cascade Layers 做优先级治理，二者配合减少样式冲突与特异性问题。

• CSS 变量承载设计令牌
• 多品牌与暗黑模式的令牌组织
• 切换性能（避免重排）

用 CSS 变量承载设计令牌（颜色、间距、圆角等），多品牌通过在不同根元素/作用域覆盖变量实现，暗黑模式通过 data-theme 或 .dark 切换变量。品牌切换时只需在根元素上变更 data-theme，CSS 变量重新计算，浏览器只重绘颜色相关部分，通常不触发重排。性能优化：变量定义最小化、避免全局选择器匹配、用 style 属性或单元素挂载减少重算。

设计令牌（CSS 变量）是主题化的基础，切换只改变量、浏览器高效重绘，无需重排。

• CSS 变量作为 token
• 语义色名（primary/background）
• 主题定制入口

shadcn/ui 用 CSS 变量作为设计 token，定义语义色（--background、--foreground、--primary、--muted 等）与圆角、间距等，组件类名引用这些变量。暗黑模式通过 .dark 作用域覆盖变量。应用：定制品牌只需改 CSS 变量，无需改组件；组件语义化命名保证一致性。它是 shadcn 主题系统的核心。

token（CSS 变量）+ 语义命名 + 作用域覆盖，是 shadcn 主题化与暗黑模式的基础。

• 浏览器内置语言检测
• 本地 AI 识别
• 应用场景

Language Detector API 是浏览器内置 AI 能力，可在本地识别文本语言（如检测为 zh/en/ja），无需云端。工程价值：用于自动翻译、输入法、内容分类、i18n 自动选择等，低延迟、隐私安全、离线可用。它是 Chrome Built-in AI 的组成部分，与现代浏览器 AI 应用协作。

Language Detector 提供本地语言识别，与翻译、i18n 等能力协作提升 AI 应用体验。

• CSS 中定义配置
• 无需 tailwind.config.js
• 与原生 CSS 融合

Tailwind v4 用 CSS-first 配置，@theme 在 CSS 中定义设计令牌，替代了 v3 的 tailwind.config.js。工程价值：配置与样式同处 CSS，直观、可被原生 CSS 复用；无需 JS 配置，减少构建配置；支持 @import 直接引入；与 CSS 模块化、设计令牌天然融合。比较适合 CSS 优先、配置简化的工程。

CSS-first 让配置"声明在 CSS 里"，减少 JS 配置负担，与原生 CSS 工作流融合。

• Lightning CSS 的 Rust 实现
• 并行处理与压缩
• 构建速度提升

Tailwind v4 使用 Lightning CSS（Rust 编写）作为 CSS 处理引擎，相比 v3 的 PostCSS 更快。Lightning CSS 支持并行、原生压缩、CSS 转换与降级，加载 JS 插件时自动回退 PostCSS。工程优势：显著提升 CSS 构建与增量编译速度，加快开发与 CI，同时保持兼容性。

Lightning CSS 以 Rust 加速 CSS 处理，是 Tailwind v4 构建速度提升的关键。

• @import 直接引入 Tailwind
• Vite 集成方式
• CSS 模块化

Tailwind v4 用 @import "tailwindcss" 一条语句引入全部（theme、base、utilities），无需 @tailwind 指令与配置文件。Vite 通过 @tailwindcss/vite 插件集成，自动处理构建与 HMR。工程应用：CSS 入口干净，可与 CSS 模块化、@layer 组织，配合 @source 扫描源码。它简化了配置与引入，契合 Vite 的现代构建。

@import 简化引入，Vite 插件零配置集成，配合 CSS 模块化组织样式。

• @theme 定义 token
• 与设计系统令牌对齐
• 生成工具类

@theme 在 CSS 中定义设计系统 token（颜色、字体、间距、阴影等），自动生成对应工具类（如 --color-brand-500 → bg-brand-500）。实践：把设计系统令牌集中定义在 @theme，与设计稿对齐，同时可引用原生 CSS 变量（--color-*: var(--x)）实现运行时切换。它为设计系统提供"单点定义 + 工具类生成"的统一入口。

@theme 让设计 token 成为 CSS 层的一等公民，自动生成工具类，是设计系统落地工具。

• @container 定义容器
• 基于容器尺寸的响应式
• 组件级自适应

Tailwind v4 原生支持容器查询，用 @container 标记容器，用 @sm/@md/@lg 等变体基于容器宽度而非视口应用样式。工程应用：让组件根据其所在容器宽度自适应，而非总是视口，适合卡片、侧栏、嵌入组件等复杂布局，实现真正的组件级响应式。

容器查询响应的是"容器尺寸"而非"视口"，让组件可复用且自适应放置环境。

• 组件源码直接复制
• @theme 与 CSS 变量集成
• 依赖配置

shadcn ui 在 Tailwind v4 下仍遵循 copy-paste 哲学：组件源码（TSX + Tailwind 类）直接复制进项目。区别是 v4 下样式配置（CSS 变量、@theme 映射）放在 CSS 中，而非 tailwind.config.js。CLI 会生成/更新 globals.css 中的变量与 @theme 映射，安装组件依赖。工程上复制即用，主题仍由 CSS 变量统一控制。

copy-paste 模式不变，只是配置从 JS 迁移到 CSS（@theme），仍需保证 CSS 变量完整。

• 配置组件路径
• 样式与别名
• 定制 CLI 行为

components.json 是 shadcn 的配置文件，声明组件存放目录（components）、非组件目录（utils）、样式（style: default/new-york）、CSS 变量前缀、tailwind 配置路径、别名（aliases）等。CLI 依据它决定组件写入位置、依赖解析与样式生成。工程应用：多项目/多包可各配 components.json，统一别名与路径，定制 CLI 行为。

components.json 是"安装约定"，让 CLI 知道组件放哪、样式怎么配、别名是什么。

• 路由树层级
• 父路由布局与子路由渲染
• Outlet 渲染子路由

嵌套路由通过路由树层级实现，父路由定义布局，子路由定义具体页面，父路由组件中用 Outlet 渲染匹配的子路由。文件路由下目录结构即嵌套层级。工程价值：共享布局（导航、侧栏）不用重复，父级 loader 可为子级准备数据，URL 层级清晰。

嵌套路由让"布局共享"与"URL 层级"统一，父布局 + Outlet 渲染子页面。

• 展示 URL 与真实 URL 分离
• 模态框场景
• 遮罩原理

Route Masking 允许在导航时展示一个 URL 而真实路由是另一个，常用于模态框：打开模态框时 URL 显示为 /photos，但实际路由是 /photos/123（模态详情）。关闭时 URL 恢复。工程价值：URL 与导航意图分离，模态框不污染历史记录，同时支持深层链接。

Route Masking 让"展示 URL"与"真实路由"解耦，适合模态框等 UI 场景。

• 路由级错误边界
• 捕获 loader/渲染错误
• 就近错误 UI

RouteErrorBoundary 在路由组件中定义，捕获该路由 loader 或渲染期间的错误，就近展示错误 UI 而非整页崩溃。它可访问错误信息与重试逻辑。工程价值：错误隔离在路由内，保证其他路由正常，配合错误提示与重试提升应用健壮性。

RouteErrorBoundary 是"路由级容错"，把错误处理限制在路由边界，避免级联崩溃。

• 版本与成熟度
• 核心能力
• 采用考量

TanStack Start 是 TanStack 的全栈框架，基于 TanStack Router + Query + Nitro + Vite，核心能力包括 server functions、SSR/streaming、文件路由、端到端类型安全。目前处于 RC 阶段，API 仍在演进，生态与文档相对较新。采用考量：功能现代、类型安全强，但稳定性和生态成熟度不如 Next.js 等项目，适合关注类型安全与全栈统一、愿承担新框架风险的团队。

Start 功能领先但 RC 阶段、生态较新，需权衡现代性与稳定性。

• 防抖/节流/限速策略
• 批量处理
• 高频交互优化

TanStack Pacer 提供防抖（debounce）、节流（throttle）、限速（rate limit）、批处理（batch）等工具，用于高频交互（搜索、滚动、拖拽）优化。工程价值：把"频率控制"抽成可复用、可测试的库，减少高频事件触发的渲染与请求，提升交互流畅度，且不绑定 React，可跨框架复用。

Pacer 把频率控制与批处理抽象成工具，是高频交互性能优化的通用方案。

• 大列表虚拟化
• List 与 Grid 的差异
• 动态尺寸

TanStack Virtual 对万级大列表只渲染可视区子项，减少 DOM 与渲染开销，提升滚动流畅度。List 与 Grid：List 是单列/单行虚拟化，Grid 是二维（多行多列）虚拟化，TanStack Virtual 通过横向 + 纵向虚拟化组合实现 Grid。取舍：List 实现简单、适合单列，Grid 需同时管理两轴虚拟化，适合表格/网格复杂布局，二者都支持动态尺寸。

List 管一维、Grid 管二维，TanStack Virtual 用两轴组合支持 Grid，兼顾性能与灵活性。

• 滚动位置与 URL 同步
• 分页/筛选状态
• 恢复滚动位置

虚拟滚动与 URL/路由器协作：把滚动位置、已加载页码或筛选条件写入 URL search，刷新后恢复。工程上，滚动容器记录 scrollTop 同步到 URL 或 history，或把当前页/游标写入 URL 实现可分享。TanStack Virtual 本身不管理 URL，需自行把滚动/分页状态与路由同步，实现刷新与分享恢复。

虚拟滚动性能由库负责，URL 同步（可分享、可恢复）需工程自行接入。

• 生态成熟度
• 迁移成本
• 取舍

TanStack Start 生态较新，核心（Router/Query/Form）成熟，但 Start 自身、全栈范式、周边（部署 preset、中间件）仍在演进，社区资源与第三方集成少于 Next.js。从纯 SPA 迁移考量：需引入 server 层、文件路由、server functions 等新概念，改造成本不小；若团队已用 TanStack 生态且追求类型安全，收益明显；若需稳定成熟生态，暂缓。总体是"现代性 vs 稳定性"的权衡。

迁移需评估新范式学习成本与生态投入，结合团队与项目需求决定。

• CSS 变量 + @theme 映射
• 语义色主题
• 暗黑模式

shadcn/ui 在 Tailwind v4 下用 CSS 变量承载语义色（--background、--primary 等），通过 @theme inline 映射为工具类，组件用类名消费。暗黑模式通过 .dark 作用域覆盖变量。工程应用：定制主题改 CSS 变量、支持多主题与暗黑、组件类名稳定，主题与组件解耦。

CSS 变量 + @theme 映射 + 作用域覆盖，构成 shadcn 在 v4 的主题系统基础。

• 框架无关的组件思想
• 各框架移植版
• 样式与逻辑分离

shadcn/ui 官方面向 React，但其"headless UI + Tailwind 样式"的哲学可通过移植版支持 Vue、Svelte、Solid 等（如 shadcn-vue、shadcn-svelte）。核心是把组件逻辑（headless）与样式（Tailwind）分离，不同框架复用同一套样式与设计令牌，逻辑用各自框架实现。工程价值：多框架项目共享设计系统与样式，但需各自维护实现。

shadcn 的样式与逻辑解耦使其可移植到多框架，各框架复用设计令牌与 Tailwind 样式。

• clsx 条件类名
• tailwind-merge 冲突解决
• 组件类名合并

cn() 是 clsx + tailwind-merge 的组合：clsx 处理条件类名（falsy 值过滤），tailwind-merge 解决 Tailwind 类冲突（如 bg-red-500 与 bg-blue-500 只保留后者）。实践：组件接收 className 时用 cn() 合并默认类与用户类，保证用户覆盖而不冲突，是 shadcn 组件可定制性的基础。

cn() 让类名合并"条件化 + 冲突自动解决"，是组件可覆盖样式的关键。

• packages/ui 承载组件
• 多应用共享
• 样式与依赖

在 monorepo 中建 packages/ui 包，把 shadcn 组件源码、utils、Tailwind/CSS 变量配置集中，作为 workspace 依赖被多个应用引用。需解决样式扫描：用 Tailwind v4 的 @source 或配置让 ui 包类被消费方扫描。工程价值：组件单一来源、多应用复用、升级一致，是 monorepo 组件共享的标准做法。

packages/ui 集中组件 + 样式配置，通过 workspace 依赖 + 样式扫描实现多应用共享。

• RHF 的非受控性能
• Zod 校验
• 组件封装

shadcn 的 form 组件基于 react-hook-form + zod，提供 FormField/FormItem 等封装，把 RHF 的受控/非受控、校验与 UI 组件结合。价值：RHF 减少重渲染、Zod 提供类型安全校验、封装简化样板，配合 shadcn 的 Input/Select 等组件，快速构建健壮表单，且类型与校验单一来源。

RHF（性能）+ Zod（类型/校验）+ shadcn 封装，是表单工程的高效组合。

• shadcn 的 Table 基础组件
• 与 TanStack Table 集成
• 排序/筛选/分页

shadcn 提供 Table 基础组件，可与 @tanstack/react-table 集成，用它的 hooks 管理排序、筛选、分页、列状态，用 shadcn 的 Table 组件渲染。工程应用：headless 逻辑 + shadcn 样式，快速构建功能完整、样式一致的表格，支持虚拟化、列配置等。二者组合是大型 CRUD 列表的常见方案。

TanStack Table 管逻辑、shadcn Table 管样式，组合实现健壮的数据表格。

• Recharts 集成
• 主题与样式统一
• 可访问性

shadcn 的 chart 组件包装 Recharts，提供 ChartContainer/ChartTooltip 等，统一主题（颜色来自 CSS 变量）、响应式与可访问性。实践：用 shadcn chart 让图表与设计系统风格一致，颜色对接 CSS 变量、支持自定义与暗黑模式，同时利用 Recharts 的图表能力。工程价值是图表 UI 与设计系统统一。

shadcn chart 把 Recharts 与设计令牌/主题打通，实现图表样式统一。

• cmdk 命令面板
• 快捷键与模糊搜索
• 组合

shadcn 的 command 组件基于 cmdk，提供命令面板/快捷键菜单，支持模糊搜索、键盘导航、分组、快捷键触发。工程价值：快速构建跨全应用的命令面板（搜索、跳转、执行操作），提升高效操作，配合 Dialog 实现可访问的快捷键面板。它让高频操作可键盘化，符合现代化效率工具。

cmdk 提供命令面板能力，shadcn 封装样式与可访问性，是效率工具的基础。

• sonner 的轻量 toast
• 样式与主题
• 交互

shadcn 的 sonner 组件提供现代 toast 通知，支持成功/错误/加载、自定义动作按钮、栈式堆叠、主题（明暗）与位置。工程应用：与 shadcn 设计系统一致，代码简洁、可访问，用于操作反馈、错误提示、异步状态。它是现代应用通知的轻量方案。

sonner 提供简洁可定制的 toast，与 shadcn 主题统一，是操作反馈的现代方案。

• next-themes 管理主题
• 暗色模式类切换
• 避免闪烁

shadcn 配合 next-themes 管理明暗主题，通过给根元素加 .dark 类切换，使用 CSS 变量组实现暗色模式。next-themes 处理初始主题、避免首屏闪烁（内联脚本）、持久化用户选择。实践：主题状态由 next-themes 管理，CSS 变量切换，组件类名不变，实现无缝暗色模式。

next-themes 管状态与持久化，CSS 变量管颜色，二者结合实现无闪烁的主题切换。