@modern-js/main-doc 2.69.4 → 3.0.0-alpha.0

package/docs/zh/guides/basic-features/render/ssr.mdx

@@ -4,26 +4,34 @@ title: 服务端渲染（SSR）
 
 # 服务端渲染（SSR）
 
-通过在服务器端将网页的 HTML 内容渲染成完整的网页（Server-Side Rendering，简称 SSR），然后将生成的网页发送到浏览器端，浏览器端只需要显示网页即可，不需要再进行额外的渲染。
+服务端渲染（Server-Side Rendering，简称 SSR）在服务器端生成完整的 HTML 页面，然后发送到浏览器端直接显示，无需客户端额外渲染。
 
-它主要的优势在于：
+## 核心优势
 
-- 提高首屏加载速度：SSR 可以在服务器端生成完整的网页，浏览器端只需要下载网页内容即可，不需要再进行额外的渲染，从而提高了首屏加载速度。
-- 有利于 SEO：SSR 可以生成完整的 HTML 内容，搜索引擎可以直接索引 HTML 内容，从而提高网站的排名。
+- **更快首屏**：服务端预渲染，浏览器直接显示，无需等待 JavaScript 执行
+- **更好 SEO**：搜索引擎可直接索引完整的 HTML 内容
+- **开箱即用**：无需编写复杂服务端逻辑，无需单独运维
 
-如果你有以下场景的需求，开发者可以考虑使用 SSR 来渲染你的页面：
+:::info 默认渲染模式
+Modern.js 的 SSR **默认使用流式渲染（Streaming SSR）**，页面会边渲染边返回，用户可以更快看到初始内容。
 
-1. 对首屏加载速度要求较高的网站，如电商网站、新闻网站等。
-2. 对用户体验要求较高的网站，如社交网站、游戏网站等。
-3. 对 SEO 要求较高的网站，如企业官网、博客等。
+详细用法请参考[流式服务端渲染（Streaming SSR）](/guides/basic-features/render/streaming-ssr)文档。
 
-在 Modern.js 中，SSR 也是开箱即用的。开发者无需为 SSR 编写复杂的服务端逻辑，也无需关心 SSR 的运维，或是创建单独的服务。
+如需切换到传统 SSR 模式（等待所有数据加载完成后一次性返回），可配置：
 
-除了开箱即用的 SSR 服务，为了保证开发者的开发体验，Modern.js 还具备：
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: {
+      mode: 'string', // 传统 SSR 模式
+    },
+  },
+});
+```
 
-- 完备的 SSR 降级策略，保证页面能够安全运行。
-- 自动分割子路由，按需加载，减少首屏资源体积。
-- 内置缓存系统，解决服务端负载高的问题。
+:::
 
 ## 开启 SSR
 
@@ -34,20 +42,19 @@ import { defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
   server: {
-    ssr: true,
+    ssr: true, // 默认启用流式渲染
   },
 });
 ```
 
 ## 数据获取
 
-:::tip 前置阅读
-如果你还不了解 Data Loader 如何使用或 Client Loader 的概念，请先阅读[数据获取](/guides/basic-features/data/data-fetch)。
-:::
+Modern.js 提供了 Data Loader，支持在 SSR 和 CSR 下同构地获取数据。每个路由模块（如 `layout.tsx` 和 `page.tsx`）都可以定义自己的 Data Loader：
 
-### 基本用法
+:::tip 了解更多
+以下方式不会有流式渲染效果，要想获得流式渲染效果请参考[流式服务端渲染（Streaming SSR）](/guides/basic-features/render/streaming-ssr)
 
-Modern.js 中提供了 Data Loader，方便开发者在 SSR、CSR 下同构地获取数据。每个路由模块，如 `layout.tsx` 和 `page.tsx` 都可以定义自己的 Data Loader：
+:::
 
 ```ts title="src/routes/page.data.ts"
 export const loader = () => {
@@ -57,7 +64,7 @@ export const loader = () => {
 };
 ```
 
-在组件中可以通过 Hooks API 的方式获取 `loader` 函数返回的数据：
+在组件中通过 Hooks API 获取数据：
 
 ```tsx
 import { useLoaderData } from '@modern-js/runtime/router';
@@ -70,9 +77,6 @@ export default () => {
 
 ### 使用 Client Loader
 
-:::info
-该功能需要 x.36.0 以上版本，推荐使用框架最新版本。
-:::
 
 默认情况下，在 SSR 应用中，`loader` 函数只会在服务端执行。但有些场景下，开发者可能期望在浏览器端发送的请求不经过 SSR 服务，直接请求数据源，例如：
 
@@ -88,16 +92,15 @@ export async function loader({ params }) {
   if (cache.has(params.id)) {
     return cache.get(params.id);
   }
-  const res = await fetch('URL_ADDRESS?id={params.id}');
+  const res = await fetch(`URL_ADDRESS?id=${params.id}`);
+  const data = await res.json();
   return {
-    message: res.message,
+    message: data.message,
   }
 }
 ```
 
-:::warning
-要使用 Client Loader，必须有对应的 Server Loader，且 Server Loader 必须是 `.data` 文件约定，不能是 `.loader` 文件约定。
-:::
+
 
 ## SSR 降级
 
@@ -281,7 +284,7 @@ Warning: Expected server HTML to contain a matching <div> in <div>.
 
 :::
 
-应用需要保持 SSR 与 CSR 渲染结果的一致性，如果存在不一致的情况，说明这部分内容无需在 SSR 中进行渲染。Modern.js 为这类在 SSR 中不需要渲染的内容提供 [`<NoSSR>` 工具组件](/apis/app/runtime/core/use-runtime-context)：
+应用需要保持 SSR 与 CSR 渲染结果的一致性，如果存在不一致的情况，说明这部分内容无需在 SSR 中进行渲染。Modern.js 为这类在 SSR 中不需要渲染的内容提供 [`<NoSSR>` 工具组件](/apis/app/runtime/ssr/no-ssr)：
 
 ```ts
 import { NoSSR } from '@modern-js/runtime/ssr';
@@ -297,8 +300,7 @@ import { NoSSR } from '@modern-js/runtime/ssr';
 
 修改代码后，刷新页发现之前的 Waring 消失。打开浏览器开发者工具的 Network 窗口，查看返回的 HTML 文档是不包含 `NoSSR` 组件包裹的内容的。
 
-在实际场景中，有些应用的 UI 展示会和用户设备有关，例如 [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 信息。Modern.js 也提供了
-[`useRuntimeContext`](/apis/app/runtime/core/use-runtime-context) 这类 API，可以在组件中获取完整的请求信息，利用它保证 SSR 与 CSR 的渲染结果一致。
+在实际场景中，有些应用的 UI 展示会和用户设备有关，例如 [UA](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 信息。Modern.js 也提供了 `use(RuntimeContext)` 这类 API，可以在组件中获取完整的请求信息，利用它保证 SSR 与 CSR 的渲染结果一致。详细用法请参考[运行时上下文](/guides/basic-features/render/before-render#运行时上下文)。
 
 ### 关注内存泄漏
 
@@ -329,3 +331,4 @@ export default function Test() {
 在浏览器端，这段代码不会造成任何问题，但是在 SSR 时，Middleware 实例会一直无法被销毁。每次渲染组件，调用 `epicMiddleware.run(rootEpic)` 时，都会在内部添加新的事件绑定，导致整个对象不断变大，最终对应用性能造成影响。
 
 CSR 中这类问题不易被发觉，因此从 CSR 切换到 SSR 时，如果不确定应用是否存在这类隐患，可以对应用进行压测。
+

package/docs/zh/guides/basic-features/render/streaming-ssr.mdx

@@ -2,22 +2,40 @@
 title: 服务端流式渲染（Streaming SSR）
 ---
 
-# 服务端流式渲染（Streaming SSR）
+# 流式服务端渲染（Streaming SSR）
 
-流式渲染是一种新的渲染方式，它可以在用户与页面交互时，实时地更新页面内容，从而提高用户体验。
+流式渲染是一种先进的渲染方式，它可以在页面渲染过程中逐步返回内容，从而显著提升用户体验。
 
-在传统的渲染方式中，页面的渲染是一次性完成的，而在流式渲染中，页面的渲染是逐步完成的，在用户与页面交互时，逐步加载数据，而不是一次性加载所有数据。
+在传统的 SSR 渲染方式中，页面的渲染是一次性完成的，需要等待所有数据加载完成后才能返回完整的 HTML。而在流式渲染中，页面的渲染是逐步完成的，可以边渲染边返回，用户能够更快地看到初始内容。
 
-相比传统渲染：
+:::info 默认模式
+**Streaming SSR 是 Modern.js SSR 的默认渲染模式**。当你启用 SSR 时，无需额外配置即可使用流式渲染。
 
-- 拥有更快感知速度：流式渲染可以在渲染过程中逐步显示内容能够以最快的速度显示业务首页。
-- 拥有更好的用户体验：通过流式渲染，用户可以更快地看到页面上的内容，而不需要等待整个页面都渲染完成后才能交互。
-- 拥有更好的性能控制：流式渲染可以让开发者更好地控制页面加载的优先级和顺序，从而更好地优化性能和用户体验。
-- 更好的适应性：流式渲染可以更好地适应不同网络速度和设备性能，使得页面在各种环境下都能有更好的表现。
+如果你需要切换到传统的 SSR 模式（等待所有数据加载完成后一次性返回），可以配置 `server.ssr.mode` 为 `'string'`。详细说明请参考[服务端渲染（SSR）](/guides/basic-features/render/ssr)文档。
+:::
+
+相比传统 SSR 渲染：
+
+- **更快感知速度**：流式渲染可以在渲染过程中逐步显示内容，能够以最快的速度显示业务首页
+- **更好的用户体验**：通过流式渲染，用户可以更快地看到页面上的内容，而不需要等待整个页面都渲染完成后才能交互
+- **更好的性能控制**：流式渲染可以让开发者更好地控制页面加载的优先级和顺序，从而更好地优化性能和用户体验
+- **更好的适应性**：流式渲染可以更好地适应不同网络速度和设备性能，使得页面在各种环境下都能有更好的表现
 
 ## 开启流式渲染
 
-Modern.js 支持了 React 18 的流式渲染，可以通过如下配置启用：
+Modern.js 支持了 React 18+ 的流式渲染。当你启用 SSR 时，流式渲染默认开启：
+
+```ts title="modern.config.ts"
+import { defineConfig } from '@modern-js/app-tools';
+
+export default defineConfig({
+  server: {
+    ssr: true, // 默认启用流式渲染
+  },
+});
+```
+
+如果你需要显式指定流式渲染模式，可以配置：
 
 ```ts title="modern.config.ts"
 import { defineConfig } from '@modern-js/app-tools';
@@ -25,7 +43,7 @@ import { defineConfig } from '@modern-js/app-tools';
 export default defineConfig({
   server: {
     ssr: {
-      mode: 'stream',
+      mode: 'stream', // 显式指定流式渲染模式
     },
   },
 });
@@ -33,7 +51,6 @@ export default defineConfig({
 
 Modern.js 的流式渲染基于 React Router 实现，主要涉及 API 有：
 
-- [`defer`](https://reactrouter.com/en/main/utils/defer)：在 Data Loader 中使用，用于支持异步获取数据。
 - [`Await`](https://reactrouter.com/en/main/components/await)：用于渲染 Data Loader 返回的异步数据。
 - [`useAsyncValue`](https://reactrouter.com/en/main/hooks/use-async-value)：用于从最近的父级 `Await` 组件中获取数据。
 
@@ -224,7 +241,7 @@ function ErrorElement() {
 
 然而，当一个爬虫访问该页面时，它可能需要先加载所有内容，直接输出整个 HTML，而不是渐进式地加载它。
 
-Modern.js 使用 [isbot](https://www.npmjs.com/package/isbot) 对请求的 `uesr-agent`，以判断请求是否来自爬虫。
+Modern.js 使用 [isbot](https://www.npmjs.com/package/isbot) 对请求的 `user-agent`，以判断请求是否来自爬虫。
 
 
 import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
@@ -233,5 +250,8 @@ import StreamSSRPerformance from '@site-docs/components/stream-ssr-performance';
 
 ## 相关文档
 
-1. [Deferred Data](https://reactrouter.com/en/main/guides/deferred)
-2. [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37)
+- [渲染模式总览](/guides/basic-features/render/overview)
+- [服务端渲染（SSR）](/guides/basic-features/render/ssr)
+- [渲染缓存](/guides/basic-features/render/ssr-cache)
+- [React Server Components（RSC）](/guides/basic-features/render/rsc) - 与 Streaming SSR 结合使用
+- [New Suspense SSR Architecture in React 18](https://github.com/reactwg/react-18/discussions/37) - React 18 架构说明

package/docs/zh/guides/basic-features/routes/_meta.json

@@ -0,0 +1 @@
+["routes", "config-routes"]

package/docs/zh/guides/basic-features/routes/config-routes.mdx

@@ -0,0 +1,426 @@
+---
+sidebar_position: 3
+---
+
+# 配置式路由
+
+默认情况下，Modern.js 推荐使用 [约定式路由](./routes.mdx) 作为路由定义的方式。同时，Modern.js 也提供了一个配置式路由的能力，其可以和约定式路由一起使用，或两者分别单独使用。
+
+
+## 何时使用配置式路由
+
+配置式路由在以下场景中特别有用：
+
+- **需要灵活的路由控制**：当文件结构无法直接映射到所需的 URL 结构时
+- **多路由指向同一组件**：需要将不同的 URL 路径指向同一个页面组件
+- **条件性路由**：根据不同条件动态配置路由
+- **遗留项目迁移**：从其他路由系统迁移到 Modern.js 时保持原有的路由结构
+- **复杂的路由命名**：需要自定义路由路径而不受文件目录限制
+
+## 基本用法
+
+在 `src` 或每个入口目录下，你可以定义一个 `modern.routes.[tj]s` 文件，通过该文件，你可以对路由进行配置：
+
+```ts
+import { defineRoutes } from '@modern-js/runtime/config-routes'
+
+export default defineRoutes(({ route, layout, page, $ }, fileRoutes) => {
+  return [
+    route("home.tsx", "/"),
+  ]
+})
+```
+
+### 函数签名说明
+
+`defineRoutes` 接受一个回调函数，该回调函数有两个参数：
+1. `routeFunctions`: 包含 `route`、`layout`、`page`、`$` 函数的对象
+2. `fileRoutes`: 约定式路由生成的路由配置数组
+
+路由函数的基本签名：
+- 第一个参数：相对于 `modern.routes.[tj]s` 的文件路径
+- 第二个参数：路由路径（可选，必须是字符串）
+- 第三个参数：子路由数组（可选）
+
+
+## 路由函数
+
+Modern.js 提供了四个主要的路由配置函数：
+
+:::tip 路径说明
+
+所有路由函数的第一个参数（路径）都是**相对路径**，会与父级路径拼接生成最终的路由路径：
+- **根路径**：`"/"` 或 "" 表示当前层级的根路径
+- **相对路径**：子路由的路径会相对于父级路径进行拼接
+- **动态路径**：使用 `:param` 语法表示动态参数
+- **通配路径**：使用 `"*"` 语法匹配所有路径
+
+:::
+
+
+:::info
+
+- `route`、`layout`、`page`、`$` 等函数的第一个参数（组件文件路径）必须指向当前项目中的真实文件，暂不支持 `node_modules` 及 Monorepo 下其他仓库中的文件
+- 不支持使用路径别名（例如 `@/pages/...`、`~/pages/...` 等）；请使用相对于 `modern.routes.[tj]s` 的相对路径。
+
+:::
+
+### `route` 函数
+
+`route` 函数是通用的路由配置函数，会根据是否有子路由自动决定生成页面路由还是布局路由，可以代替 `layout`, `page`, `$`等函数。
+
+```ts
+export default defineRoutes(({ route }, fileRoutes) => {
+  return [
+    // 无子路由时，自动生成页面路由
+    route("home.tsx", "/"),
+    route("about.tsx", "about"),
+
+    // 有子路由时，自动生成布局路由
+    // dashboard/layout.tsx 需要包含 <Outlet> 来渲染子路由
+    route("dashboard/layout.tsx", "dashboard", [
+      route("dashboard/overview.tsx", "overview"),  // 生成路径：/dashboard/overview
+      route("dashboard/settings.tsx", "settings"),  // 生成路径：/dashboard/settings
+    ]),
+
+    // 动态路由
+    route("products/detail.tsx", "products/:id"),
+
+    // 多路径指向同一组件
+    route("user/profile.tsx", "user"),
+    route("user/profile.tsx", "profile"),
+  ]
+})
+```
+
+**使用场景**：
+- 快速配置路由，无需明确指定是页面还是布局
+- 简化路由配置的复杂度
+
+### `layout` 函数
+
+`layout` 函数专门用于配置布局路由，始终生成布局组件，必须包含子路由：
+
+```ts
+export default defineRoutes(({ layout, page }, fileRoutes) => {
+  return [
+    // 生成布局路由，路径为 "/auth"，必须包含子路由
+    layout("auth/layout.tsx", "auth", [
+      page("auth/login/page.tsx", "login"),      // 生成路径：/auth/login
+      page("auth/register/page.tsx", "register"), // 生成路径：/auth/register
+    ]),
+  ]
+})
+```
+
+**使用场景**：
+- 需要明确指定某个组件为布局组件
+- 为多个页面提供共同的布局结构
+- 需要在多个路由间共享导航、侧边栏等UI组件
+
+### `page` 函数
+
+`page` 函数专门用于配置页面路由，始终生成页面组件：
+
+```ts
+export default defineRoutes(({ layout, page }, fileRoutes) => {
+  return [
+    layout("dashboard/layout.tsx", "dashboard", [
+      page("dashboard/overview.tsx", "overview"),  // 生成路径：/dashboard/overview
+      page("dashboard/settings.tsx", "settings"),  // 生成路径：/dashboard/settings
+    ]),
+  ]
+})
+```
+
+**使用场景**：
+- 需要明确指定某个组件为页面组件
+- 确保组件不包含 `<Outlet>` 子组件渲染
+- 提供更清晰的语义表达
+
+### `$` 函数
+
+`$` 函数专门用于配置通配路由，用于处理未匹配的路由：
+
+```ts
+export default defineRoutes(({ layout, page, $ }, fileRoutes) => {
+  return [
+    layout("blog/layout.tsx", "blog", [
+      page("blog/page.tsx", ""),                    // 生成路径：/blog
+      page("blog/[id]/page.tsx", ":id"),            // 生成路径：/blog/:id
+      $("blog/$.tsx", "*"),                         // 通配路由，匹配 /blog 下的所有未匹配路径
+    ]),
+  ]
+})
+```
+
+**使用场景**：
+- 自定义 404 页面
+- 处理特定路径下的所有未匹配请求
+
+:::tip
+`$` 函数与约定式路由中的 `$.tsx` 文件功能相同，用于捕获未匹配的路由请求。
+:::
+
+## 配置路由
+
+### 基本示例
+
+```ts
+export default defineRoutes(({ page }, fileRoutes) => {
+  return [
+    // 使用 page 函数明确指定页面路由
+    page("home.tsx", "/"),
+    page("about.tsx", "about"),
+    page("contact.tsx", "contact"),
+  ]
+})
+```
+
+### 无路径路由
+
+当不指定路径时，路由会继承父级路径：
+
+```ts
+export default defineRoutes(({ layout, page }, fileRoutes) => {
+  return [
+    // 使用 layout 函数明确指定布局路由
+    // auth/layout.tsx 需要包含 <Outlet> 来渲染子路由
+    layout("auth/layout.tsx", [
+      page("login/page.tsx", "login"),
+      page("register/page.tsx", "register"),
+    ]),
+  ]
+})
+```
+
+上述配置会生成：
+- `/login` → `auth/layout.tsx` + `login/page.tsx`
+- `/register` → `auth/layout.tsx` + `register/page.tsx`
+
+### 多路径指向同一组件
+
+```ts
+export default defineRoutes(({ page }, fileRoutes) => {
+  return [
+    page("user.tsx", "user"),
+    page("user.tsx", "profile"),
+    page("user.tsx", "account"),
+  ]
+})
+```
+
+### 动态路由
+
+配置式路由支持动态路由参数：
+
+```ts
+export default defineRoutes(({ page }, fileRoutes) => {
+  return [
+    // 必需参数
+    page("blog/detail.tsx", "blog/:id"),
+
+    // 可选参数
+    page("blog/index.tsx", "blog/:slug?"),
+  ]
+})
+```
+
+## 路由相关文件自动查找
+
+配置式路由会自动查找组件的配套文件，无需手动配置。对于 `modern.routes.[tj]s` 中指定的任意组件文件，Modern.js 会自动查找以下配套文件：
+
+```ts
+// modern.routes.[tj]s
+export default defineRoutes(({ route }, fileRoutes) => {
+  return [
+    route("pages/profile.tsx", "profile"),
+    route("pages/user/detail.tsx", "user/:id"),
+  ]
+})
+```
+
+Modern.js 会自动查找并加载：
+
+- `pages/profile.data.ts` → 数据加载器
+- `pages/profile.config.ts` → 路由配置
+- `pages/profile.error.tsx` → 错误边界
+- `pages/profile.loading.tsx` → Loading 组件
+
+### 查找规则
+
+- **文件位置**：配套文件必须与组件文件在同一目录
+- **文件命名**：配套文件名与组件文件名相同（不包括扩展名）
+- **自动发现**：Modern.js 自动发现并加载这些文件
+
+:::tip
+
+更多关于数据获取的详细信息，请参考 [数据获取](/guides/basic-features/data/data-fetch) 文档。关于 Loading 组件的使用，请参考 [约定式路由 - Loading](./routes.mdx#loading-experimental)。
+
+:::
+
+
+## 路由合并
+
+配置式路由可以与约定式路由一起使用，你可以通过修改 `fileRoutes` 参数来实现路由的合并：
+
+1. **覆盖路由**：可以主动移除约定式路由并替换为配置式路由
+2. **补充路由**：可以在约定式路由基础上添加新的配置式路由
+3. **混合使用**：可以在约定式布局路由下添加配置式子路由
+
+:::info
+
+当前路由结构可以通过 [`modern routes`](#调试路由) 命令查看
+
+:::
+
+
+### 合并示例
+
+以下示例展示了配置式路由与约定式路由的合并方式：
+
+```ts
+// modern.routes.ts
+import { defineRoutes } from '@modern-js/runtime/config-routes';
+
+export default defineRoutes(({ page }, fileRoutes) => {
+  // 场景1：覆盖约定式路由
+  // 移除原有的 shop 路由，替换为自定义组件
+  const shopPageIndex = fileRoutes[0].children?.findIndex(
+    route => route.id === 'three_shop/page',
+  );
+  fileRoutes[0].children?.splice(shopPageIndex!, 1);
+  fileRoutes[0].children?.push(page('routes/CustomShop.tsx', 'shop'));
+
+  // 场景2：补充约定式路由
+  // 添加配置式路由，无约定式路由对应
+  fileRoutes[0].children?.push(page('routes/Settings.tsx', 'settings'));
+
+  // 场景3：混合嵌套路由
+  // 在约定式布局路由下添加配置式子路由
+  const userRoute = fileRoutes[0].children?.find(
+    (route: any) => route.path === 'user',
+  );
+  if (userRoute?.children) {
+    userRoute.children.push(page('routes/user/CustomTab.tsx', 'custom-tab'));
+  }
+
+  // 场景4：自动发现配套文件
+  // Product.tsx 会自动发现 Product.data.ts 和 Product.error.tsx
+  fileRoutes[0].children?.push(page('routes/Product.tsx', 'product/:id'));
+
+  return fileRoutes;
+});
+```
+## 调试路由
+
+由于路由合并后的最终结构可能不够直观，Modern.js 提供了调试命令来帮助你查看完整路由信息：
+
+```bash
+# 生成路由结构分析报告
+npx modern routes
+```
+
+该命令会在 `dist/routes-inspect.json` 文件中生成最终的路由结构，帮助你了解合并后的完整路由信息。
+
+### 报告文件示例
+
+#### 单入口场景
+
+```json title="dist/routes-inspect.json"
+{
+  "routes": [
+    {
+      "path": "/",
+      "component": "@_modern_js_src/routes/page",
+      "data": "@_modern_js_src/routes/page.data",
+      "clientData": "@_modern_js_src/routes/page.data.client",
+      "error": "@_modern_js_src/routes/page.error",
+      "loading": "@_modern_js_src/routes/page.loading"
+    },
+    {
+      "path": "/dashboard",
+      "component": "pages/admin",
+      "config": "pages/admin.config",
+      "error": "pages/admin.error"
+    },
+    {
+      "path": "/user",
+      "component": "layouts/user",
+      "children": [
+        {
+          "path": "/user/profile",
+          "component": "@_modern_js_src/routes/user/profile",
+          "data": "@_modern_js_src/routes/user/profile.data"
+        }
+      ]
+    },
+    {
+      "path": "@_modern_js_src/routes/blog/:id",
+      "component": "blog/detail",
+      "params": ["id"],
+      "data": "blog/detail.data",
+      "loading": "blog/detail.loading"
+    },
+    {
+      "path": "/files/*",
+      "component": "@_modern_js_src/routes/files/list"
+    }
+  ]
+}
+```
+
+#### 多入口场景
+
+在多入口项目中，报告文件会按照入口名称进行分组，其中 key 为 entryName：
+
+```json title="dist/routes-inspect.json"
+{
+  "main": {
+    "routes": [
+      {
+        "path": "/",
+        "component": "@_modern_js_src/routes/page",
+        "data": "@_modern_js_src/routes/page.data",
+        "error": "@_modern_js_src/routes/page.error",
+        "loading": "@_modern_js_src/routes/page.loading"
+      },
+      {
+        "path": "/dashboard",
+        "component": "@_modern_js_src/routes/dashboard",
+        "config": "@_modern_js_src/routes/dashboard.config"
+      }
+    ]
+  },
+  "admin": {
+    "routes": [
+      {
+        "path": "/",
+        "component": "@_modern_js_src/routes/dashboard",
+        "data": "@_modern_js_src/routes/dashboard.data",
+        "clientData": "@_modern_js_src/routes/dashboard.data.client",
+        "config": "@_modern_js_src/routes/dashboard.config"
+      },
+      {
+        "path": "/users",
+        "component": "@_modern_js_src/routes/users",
+        "data": "@_modern_js_src/routes/users.data",
+        "error": "@_modern_js_src/routes/users.error",
+        "loading": "@_modern_js_src/routes/users.loading"
+      }
+    ]
+  }
+}
+```
+
+#### 路由相关文件字段说明
+
+报告中除了基本的路由信息外，还会显示每个路由找到的相关文件：
+
+- **`data`**: 服务端数据加载文件（`.data.ts`），用于在服务端获取数据
+- **`clientData`**: 客户端数据加载文件（`.data.client.ts`），用于在客户端重新获取数据
+- **`error`**: 错误边界文件（`.error.tsx`），用于处理路由渲染错误
+- **`loading`**: 加载状态组件文件（`.loading.tsx`），用于显示数据加载中的状态
+- **`config`**: 路由配置文件（`.config.ts`），用于配置路由元数据
+
+这些字段都是可选的，只有在找到对应文件时才会在报告中显示。通过查看这些字段，你可以快速了解每个路由的完整文件结构。