基于文件的路由

大多数 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>

扁平路由

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

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

请看下面的例子

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

混合扁平路由和目录路由

100% 目录或扁平路由结构不太可能最适合您的项目，这就是为什么 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>

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

基于文件的路由入门

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

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

• 使用 Vite 进行配置

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

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