TanStack Router 基于文件的路由

TanStack Router 的大部分文档都是基于"基于文件的路由"这一视角编写的，旨在帮助你深入理解如何配置它以及其背后的技术细节。虽然基于文件的路由是配置 TanStack Router 的首选和推荐方式 ，但如果你愿意，也可以使用基于代码的路由。

什么是基于文件的路由？

基于文件的路由是一种利用文件系统来配置路由的方式。你不需要通过代码定义路由结构，而是通过一系列代表应用程序路由层级的文件和目录来定义路由。这带来了许多好处：

简单性 (Simplicity)：对于新手和经验丰富的开发者来说，基于文件的路由都在视觉上更直观且易于理解。
组织性 (Organization)：路由的组织方式直接镜像了应用程序的 URL 结构。
可扩展性 (Scalability)：随着应用程序的增长，基于文件的路由使得添加新路由和维护现有路由变得容易。
代码分割 (Code-Splitting)：基于文件的路由允许 TanStack Router 自动对路由进行代码分割，以获得更好的性能。
类型安全 (Type-Safety)：基于文件的路由通过自动生成和管理路由的类型链接，极大提升了类型安全的上限，而在基于代码的路由中，这通常是一个繁琐的过程。
一致性 (Consistency)：基于文件的路由强制执行一致的路由结构，使得维护、更新应用程序以及在不同项目间迁移变得更加容易。

虽然目录长期以来一直用于表示路由层级，但基于文件的路由引入了一个额外的概念：在文件名中使用 . 字符来表示路由嵌套。这允许你避免为少量深度嵌套的路由创建目录，同时继续为更广泛的路由层级使用目录。让我们看一些例子！

目录可用于表示路由层级，这对于将多个路由组织成逻辑组以及减少大量深度嵌套路由的文件名长度非常有用。

请看下面的例子：

文件名 (Filename)	路由路径 (Route Path)	组件输出 (Component Output)
ʦ `__root.tsx`		`<Root>`
ʦ `index.tsx`	`/` (精确匹配)	`<Root><RootIndex>`
ʦ `about.tsx`	`/about`	`<Root><About>`
ʦ `posts.tsx`	`/posts`	`<Root><Posts>`
📂 `posts`
┄ ʦ `index.tsx`	`/posts` (精确匹配)	`<Root><Posts><PostsIndex>`
┄ ʦ `$postId.tsx`	`/posts/$postId`	`<Root><Posts><Post>`
📂 `posts_`
┄ 📂 `$postId`
┄ ┄ ʦ `edit.tsx`	`/posts/$postId/edit`	`<Root><EditPost>`
ʦ `settings.tsx`	`/settings`	`<Root><Settings>`
📂 `settings`
┄ ʦ `profile.tsx`	`/settings/profile`	`<Root><Settings><Profile>`
┄ ʦ `notifications.tsx`	`/settings/notifications`	`<Root><Settings><Notifications>`
ʦ `_pathlessLayout.tsx`		`<Root><PathlessLayout>`
📂 `_pathlessLayout`
┄ ʦ `route-a.tsx`	`/route-a`	`<Root><PathlessLayout><RouteA>`
┄ ʦ `route-b.tsx`	`/route-b`	`<Root><PathlessLayout><RouteB>`
📂 `files`
┄ ʦ `$.tsx`	`/files/$`	`<Root><Files>`
📂 `account`
┄ ʦ `route.tsx`	`/account`	`<Root><Account>`
┄ ʦ `overview.tsx`	`/account/overview`	`<Root><Account><Overview>`

扁平路由赋予你使用 . 来表示路由嵌套层级的能力。

当你有大量独特的深度嵌套路由，并且希望避免为每一个路由都创建目录时，这非常有用：

请看下面的例子：

文件名 (Filename)	路由路径 (Route Path)	组件输出 (Component Output)
ʦ `__root.tsx`		`<Root>`
ʦ `index.tsx`	`/` (精确匹配)	`<Root><RootIndex>`
ʦ `about.tsx`	`/about`	`<Root><About>`
ʦ `posts.tsx`	`/posts`	`<Root><Posts>`
ʦ `posts.index.tsx`	`/posts` (精确匹配)	`<Root><Posts><PostsIndex>`
ʦ `posts.$postId.tsx`	`/posts/$postId`	`<Root><Posts><Post>`
ʦ `posts_.$postId.edit.tsx`	`/posts/$postId/edit`	`<Root><EditPost>`
ʦ `settings.tsx`	`/settings`	`<Root><Settings>`
ʦ `settings.profile.tsx`	`/settings/profile`	`<Root><Settings><Profile>`
ʦ `settings.notifications.tsx`	`/settings/notifications`	`<Root><Settings><Notifications>`
ʦ `_pathlessLayout.tsx`		`<Root><PathlessLayout>`
ʦ `_pathlessLayout.route-a.tsx`	`/route-a`	`<Root><PathlessLayout><RouteA>`
ʦ `_pathlessLayout.route-b.tsx`	`/route-b`	`<Root><PathlessLayout><RouteB>`
ʦ `files.$.tsx`	`/files/$`	`<Root><Files>`
ʦ `account.tsx`	`/account`	`<Root><Account>`
ʦ `account.overview.tsx`	`/account/overview`	`<Root><Account><Overview>`

极有可能 100% 的目录结构或 100% 的扁平路由结构都不完全适合你的项目，这就是为什么 TanStack Router 允许你将扁平路由和目录路由混合使用，从而创建一个结合两者优点的路由树。

请看下面的例子：

文件名 (Filename)	路由路径 (Route Path)	组件输出 (Component Output)
ʦ `__root.tsx`		`<Root>`
ʦ `index.tsx`	`/` (精确匹配)	`<Root><RootIndex>`
ʦ `about.tsx`	`/about`	`<Root><About>`
ʦ `posts.tsx`	`/posts`	`<Root><Posts>`
📂 `posts`
┄ ʦ `index.tsx`	`/posts` (精确匹配)	`<Root><Posts><PostsIndex>`
┄ ʦ `$postId.tsx`	`/posts/$postId`	`<Root><Posts><Post>`
┄ ʦ `$postId.edit.tsx`	`/posts/$postId/edit`	`<Root><Posts><Post><EditPost>`
ʦ `settings.tsx`	`/settings`	`<Root><Settings>`
ʦ `settings.profile.tsx`	`/settings/profile`	`<Root><Settings><Profile>`
ʦ `settings.notifications.tsx`	`/settings/notifications`	`<Root><Settings><Notifications>`
ʦ `account.tsx`	`/account`	`<Root><Account>`
ʦ `account.overview.tsx`	`/account/overview`	`<Root><Account><Overview>`

扁平路由和目录路由可以混合在一起，以便在合理的地方结合两者的优点来创建路由树。

$!TIP$
如果你发现默认的基于文件的路由结构不符合你的需求，你始终可以使用虚拟文件路由 (Virtual File Routes) 来控制路由的来源，同时仍然享受基于文件路由带来的出色性能优势。

要开始使用基于文件的路由，你需要配置你项目的打包工具（Bundler）以使用 TanStack Router Plugin 或 TanStack Router CLI。

要启用基于文件的路由，你需要在使用 React 的同时使用受支持的打包工具。请查看下面的配置指南，看看你的打包工具是否在列表中。

当通过受支持的打包工具使用 TanStack Router 的基于文件的路由时，插件将通过打包工具的开发和构建过程自动生成你的路由配置。这是使用 TanStack Router 路由生成功能最简单的方法。