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(布局名是路径一部分)。
-