Tanstack Router 文件命名速查表

1. 基础与嵌套 (Basic Structure)

符号 / 规则	作用	文件名示例	对应 URL / 效果	核心逻辑
__root.tsx	根组件	src/routes/__root.tsx	全局	整个应用的入口外壳 (HTML/Body)。
. (点)	嵌套层级	blog.post.tsx	/blog/post	用点代替文件夹，扁平化写法。
index	默认页	posts.index.tsx	/posts	父级路径的“首页” (精确匹配时显示)。
route.tsx	目录布局	settings/route.tsx	/settings	等同于 settings.tsx，文件夹模式下的父级布局。

2. 动态参数 (Dynamic Params)

符号 / 规则	作用	文件名示例	对应 URL / 效果	核心逻辑
$	变量/参数	posts.$id.tsx	/posts/123 /posts/abc	$ 后的单词变为参数名 (如 params.id)。
$ (单独)	通配符 (Splat)	files.$.tsx	/files/a/b/c	贪婪匹配后面所有的路径片段。

3. 布局与组织 (Layouts & Organization)

符号 / 规则	作用	文件名示例	对应 URL / 效果	核心逻辑
_ (前缀)	无路径布局	_auth.login.tsx	/login	不影响 URL，只套用 _auth.tsx 的布局组件。
(xxx)	路由组	(app)/dashboard.tsx	/dashboard	完全透明，仅用于文件夹分类 (如把管理端页面归类)。
- (前缀)	忽略文件	-components/Nav.tsx	(无)	不生成路由，可放组件、工具函数等。

4. 特殊处理 (Advanced)

符号 / 规则	作用	文件名示例	对应 URL / 效果	核心逻辑
_ (后缀)	非嵌套路由	posts_.$id.edit.tsx	/posts/123/edit	逃离父级 posts.tsx 的布局，独立全屏渲染。
[ ]	转义字符	abc[.]def.tsx	/abc.def	强制保留文件名中的点，不被解析为嵌套。

---

⚡️ 一眼看懂对比

为了加深印象，这几个容易混淆的用法我单独列出来对比：

• posts.tsx 🆚 posts/route.tsx

  • 效果一样：都定义 /posts 这个层级的布局（父级）。

  • 区别：前者是扁平文件，后者是目录文件。

• posts/index.tsx 🆚 posts.tsx

  • posts.tsx：是框（Layout），不管去 /posts 还是 /posts/123 都在。

  • posts/index.tsx：是内容，只有访问 /posts 时才在框里显示。

• _layout.a.tsx 🆚 layout.a.tsx

  • _layout.a.tsx (前缀 _)：URL 是 /a (布局名隐身)。

  • layout.a.tsx (无前缀)：URL 是 /layout/a (布局名是路径一部分)。