React Router V7框架模式下嵌套路由的文件夹配置问题

问题原因 #

React Router V7 的 flatRoutes 默认不会将文件夹内的非index.tsx文件识别为子路由——官方文档明确说明“文件夹中的所有其他模块不会成为路由”，这和早期版本的行为不同。你当前的/routes/admin/index.tsx仅对应/admin路径，而/routes/admin/users.tsx不会被自动映射为/admin/users，导致404。

解决方法 #

要实现文件夹内的子路由映射，需要用**layout.tsx作为父路由容器**，配合文件夹内的页面文件来生成嵌套路由：

1. 调整目录结构 #

将原有的admin/index.tsx改为admin/layout.tsx，同时保留admin/index.tsx作为/admin的页面内容，结构如下：

/routes/
├── admin/
│   ├── layout.tsx    # 父路由容器，负责渲染子路由
│   ├── index.tsx     # 对应 /admin 页面
│   └── users.tsx     # 对应 /admin/users 页面
├── public/
├── organization/
└── Routes.ts

2. 编写layout.tsx内容 #

layout.tsx需要引入Outlet组件，用来渲染子路由的内容。如果不需要公共布局（比如侧边栏、导航栏），可以直接返回Outlet：

import { Outlet } from 'react-router-dom';

export default function AdminLayout() {
  // 这里可以添加Admin模块的公共UI（如侧边栏、顶部导航）
  return <Outlet />;
}

3. 保持Routes.ts不变 #

你的Routes.ts代码无需修改，flatRoutes()会自动识别新的结构：

import { type RouteConfig } from '@react-router/dev/routes';
import { flatRoutes } from '@react-router/fs-routes';

export default flatRoutes() satisfies RouteConfig;

这样调整后，访问/admin会加载admin/layout.tsx包裹admin/index.tsx，访问/admin/users会加载admin/layout.tsx包裹admin/users.tsx，不会再出现404问题。

补充说明 #

如果你不需要公共布局，只是想通过文件夹组织路由文件，layout.tsx可以仅作为路由容器存在，不添加额外UI，完全替代原来的index.tsx作为父路由的入口。而你之前用的admin.tsx+admin.users.tsx的扁平命名方式，本质是通过文件名的.分隔符生成嵌套路由，和文件夹+layout的方式效果一致，但后者更适合大规模模块的文件组织。

内容的提问来源于stack exchange，提问作者Mark Swardstrom