基于文件的路由

大多数 TanStack Router 文档都是为基于文件的路由编写的，旨在帮助您更详细地了解如何配置基于文件的路由以及其工作原理背后的技术细节。虽然基于文件的路由是配置 TanStack Router 的首选和推荐方式，但如果您愿意，也可以使用基于代码的路由。

什么是基于文件的路由？

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

• 简单性：基于文件的路由在视觉上直观，新老开发人员都易于理解。
• 组织性：路由的组织方式与应用程序的 URL 结构相对应。
• 可伸缩性：随着应用程序的增长，基于文件的路由可以轻松添加新路由并维护现有路由。
• 代码分割：基于文件的路由允许 TanStack Router 自动对路由进行代码分割，以获得更好的性能。
• 类型安全：基于文件的路由通过生成和管理路由的类型链接来提高类型安全的上限，否则这通过基于代码的路由可能是一个繁琐的过程。
• 一致性：基于文件的路由强制执行路由的一致结构，使其更容易维护和更新您的应用程序，并从一个项目切换到另一个项目。

/还是.？

虽然目录长期以来一直用于表示路由层次结构，但基于文件的路由引入了一个附加概念，即在文件名中使用.字符来表示路由嵌套。这使您可以避免为少数深度嵌套的路由创建目录，并继续为更宽的路由层次结构使用目录。让我们看一些例子！

目录路由

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

请看下面的例子

文件名	路由路径	组件输出
ʦ __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		<Root><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>

扁平路由

平坦路由允许您使用.来表示路由嵌套级别。

当您有大量唯一的深度嵌套路由并希望避免为每个路由创建目录时，这会很有用

请看下面的例子

文件名	路由路径	组件输出
ʦ __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>

混合平坦和目录路由

您的项目极有可能不会完全使用目录或平坦路由结构，这就是为什么 TanStack Router 允许您将平坦路由和目录路由混合使用，以创建一种在需要时利用两者优点的路由树。

请看下面的例子

文件名	路由路径	组件输出
ʦ __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>

平坦路由和目录路由可以混合使用，以创建一种在需要时利用两者优点的路由树。

开始使用基于文件的路由

要开始使用基于文件的路由，您需要配置项目的打包器以使用 TanStack Router 插件或 TanStack Router CLI。

要启用基于文件的路由，您需要使用 React 和受支持的打包器。请查看您的打包器是否在下面的配置指南中列出。

• Vite 安装
• Rspack/Rsbuild 安装
• Webpack 安装
• Esbuild 安装

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

如果您的打包器尚未受支持，您可以在 Discord 或 GitHub 上与我们联系。在此之前，请不要担心！您仍然可以使用@tanstack/router-cli包来生成您的路由树文件。