基于文件的路由

大多数 TanStack Router 文档是为基于文件的路由编写的，旨在帮助您更详细地了解如何配置基于文件的路由以及其工作原理背后的技术细节。虽然基于文件的路由是配置 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>

扁平路由使您能够使用 . 来表示路由嵌套级别。

当您有大量唯一深度嵌套的路由并且想要避免为每个路由创建目录时，这非常有用

请看下面的例子

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

完全目录或扁平路由结构极不可能最适合您的项目，这就是 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>

扁平路由和目录路由可以混合在一起，以创建一个路由树，该路由树在有意义的地方使用了两者的优点。

提示

如果您发现默认的基于文件的路由结构不符合您的需求，您可以随时使用虚拟文件路由来控制路由的来源，同时仍然获得基于文件的路由的出色性能优势。

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

要启用基于文件的路由，您需要将 React 与受支持的 bundler 一起使用。查看您的 bundler 是否在下面的配置指南中列出。

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

如果您的 bundler 尚未受支持，您可以在 Discord 或 GitHub 上联系我们告知。在那之前，请不要害怕！您仍然可以使用 @tanstack/router-cli 包来生成您的路由树文件。