@modern-js/main-doc 0.0.0-nightly-20240827170702 → 0.0.0-nightly-20240829170706

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

@@ -2,20 +2,22 @@
 sidebar_position: 2
 ---
 
-# 路由方案
+# 路由
 
-Modern.js 的路由基于 [React Router 6](https://reactrouter.com/en/main)，并提供了多种类型的路由模式。根据不同 [入口](/guides/concept/entries) 类型，将路由分为三种模式，分别是**约定式路由**，**自控式路由**和**其他路由方案**。
+Modern.js 的路由基于 [React Router 6](https://reactrouter.com/en/main)，提供了基于文件约定的路由能力，并支持了业界流行的约定式路由模式：**嵌套路由**。当入口被识别为 [约定式路由](/guides/concept/entries.html#约定式路由) 时，Modern.js 会自动基于文件系统，生成对应的路由结构。
 
 :::note
-本小节提到的路由，都是客户端路由，即 SPA 路由。
-
+本小节提到的路由，都是约定式路由。
 :::
 
-## 约定式路由
+## 什么是嵌套路由
+
+嵌套路由是一种将 URL 分段与组件层次结构和数据耦合起来的路由模式。通常，URL 段会决定：
 
-以 `routes/` 为约定的入口，Modern.js 会自动基于文件系统，生成对应的路由结构。
+- 页面上要渲染的布局
+- 这些布局的数据依赖
 
-Modern.js 支持了业界流行的约定式路由模式：**嵌套路由**，使用嵌套路由时，页面的路由 与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
+因此，使用嵌套路由时，页面的路由与 UI 结构是相呼应的，我们将会详细介绍这种路由模式。
 
 ```bash
 /user/johnny/profile                  /user/johnny/posts
@@ -28,61 +30,44 @@ Modern.js 支持了业界流行的约定式路由模式：**嵌套路由**，使
 +------------------+                  +-----------------+
 ```
 
-### 路由文件约定
+## 路由文件约定
 
-在`routes/` 目录下，目录名会作为路由 url 的映射，Modern.js 有两个文件约定 `layout.[jt]sx` 和 `page.[jt]sx`（后面简写为 `.tsx`）。这两个文件决定了应用的布局层次，其中 `layout.tsx` 中作为布局组件，`page.tsx` 作为内容组件，是整条路由的叶子节点（一条路由有且仅有一个叶子节点，且必须以叶子节点结尾）。
-
-例如以下目录结构：
+在 `routes/` 目录下，子目录名会作为路由 URL 的映射，Modern.js 有两个文件约定 `layout.tsx` 和 `page.tsx`。这两个文件决定了应用的布局层次，其中：
 
-```bash
-.
-└── routes
-    ├── page.tsx
-    └── user
-        └── page.tsx
-```
+- `page.tsx` 为内容组件，所在目录下存在该文件时，对应的路由 URL 可访问。
+- `layout.tsx` 为布局组件，控制所在目录下所有子路由的布局，使用 `<Outlet>` 表示子组件。
 
-会产出下面两条路由：
+:::tip
+`.ts`、`.js`、`.jsx` 或 `.tsx` 文件扩展名可用于上述约定文件。
+:::
 
-- `/`
-- `/user`
+### Page
 
-当添加 `layout.tsx` 后， 假设有以下目录
+`<Page>` 组件是指 `routes/` 目录下所有 `page.tsx` 文件，也是所有路由的叶子组件。除了通配路由外，任何路由都应该由 `<Page>` 组件结束。
 
-:::info
-这里 `routes/layout.tsx` 会作为 `/` 路由下所有组件的布局组件使用， `routes/user/layout.tsx` 会作为 `/user` 路由下所有路由组件的布局组件使用。
+```tsx title=routes/page.tsx
+export default () => {
+  return <div>Hello world</div>
+};
+```
 
-:::
+当应用中存在以下目录结构时：
 
 ```bash
 .
 └── routes
-    ├── layout.tsx
     ├── page.tsx
     └── user
-        ├── layout.tsx
         └── page.tsx
 ```
 
-当路由为 `/` 时，会有以下 UI 布局：
-
-```tsx
-<Layout>
-  <Page />
-</Layout>
-```
+会产出下面两条路由：
 
-同样，`routes/user/layout.tsx` 会作为 `/user` 路由下所有组件的布局组件使用。当路由为 `/user` 时， 会有以下 UI 布局：
+- `/`
+- `/user`
 
-```tsx
-<Layout>
-  <UserLayout>
-    <UserPage />
-  </UserLayout>
-</Layout>
-```
 
-#### Layout
+### Layout
 
 `<Layout>` 组件是指 `routes/` 目录下所有 `layout.tsx` 文件，它们表示对应路由片段的布局，使用 `<Outlet>` 表示子组件。
 
@@ -99,11 +84,10 @@ export default () => {
 ```
 
 :::note
-`<Outlet>` 是 React Router 6 中新的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet).
-
+`<Outlet>` 是 React Router 6 中提供的 API，详情可以查看 [Outlet](https://reactrouter.com/en/main/components/outlet#outlet)。
 :::
 
-为了方便介绍 `<Layout>` 与 `<Outlet>` 的关系，以下面的文件目录举例：
+不同目录结构下，`<Outlet>` 所代表的组件也不同。为了方便介绍 `<Layout>` 与 `<Outlet>` 的关系，以下面的文件目录举例：
 
 ```bash
 .
@@ -117,7 +101,7 @@ export default () => {
         └── page.tsx
 ```
 
-1. 当路由为 `/` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/page.tsx` 中导出的组件，生成以下 UI 结构：
+1. 当路由为 `/` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/page.tsx` 中导出的组件，路由的 UI 结构为：
 
 ```tsx
 <Layout>
@@ -125,7 +109,7 @@ export default () => {
 </Layout>
 ```
 
-2. 当路由为 `/blog` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/blog/page.tsx` 中导出的组件，生成以下 UI 结构：
+2. 当路由为 `/blog` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/blog/page.tsx` 中导出的组件，路由的 UI 结构为：
 
 ```tsx
 <Layout>
@@ -133,7 +117,7 @@ export default () => {
 </Layout>
 ```
 
-3. 当路由为 `/user` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/user/layout.tsx` 中导出的组件。`routes/user/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/user/page.tsx` 中导出的组件。生成以下 UI 结构：
+3. 当路由为 `/user` 时，`routes/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/user/layout.tsx` 中导出的组件。`routes/user/layout.tsx` 中的 `<Outlet>` 代表的是 `routes/user/page.tsx` 中导出的组件，路由的 UI 结构为：
 
 ```tsx
 <Layout>
@@ -145,43 +129,16 @@ export default () => {
 
 总结而言，如果子路由的文件目录下存在 `layout.tsx`，上一级 `layout.tsx` 中的 `<Outlet>` 即为子路由文件目录下的 `layout.tsx` ，否则为子路由文件目录下的 `page.tsx`。
 
-#### Page
-
-所有的路由，理论上都应该由 `<Page>` 组件结束。在 `page.tsx` 文件内，如果开发者引入 `<Outlet>` 组件，不会有任何效果。
-
-#### Config
-
-每个 `Layout`, `$` 或 `Page` 文件都可以定义一个自己的 `config` 文件，如 `page.config.ts`，该文件中我们约定了一个具名导出 `handle`，
-这个字段中你可以定义任意属性：
-
-```ts title="routes/page.config.ts"
-export const handle = {
-  breadcrumbName: 'profile',
-};
-```
-
-定义的这些属性可以通过 [`useMatches`](https://reactrouter.com/en/main/hooks/use-matches) hook 获取：
-
-```ts title="routes/layout.ts"
-export default () => {
-  const matches = useMatches();
-  const breadcrumbs = matches.map(
-    matchedRoute => matchedRoute?.handle?.breadcrumbName,
-  );
-  return <Breadcrumb names={breadcrumbs}></Breadcrumb>;
-};
-```
-
-### 动态路由
+## 动态路由
 
 通过 `[]` 命名的文件目录，生成的路由会作为动态路由。例如以下文件目录：
 
 ```bash
+.
 └── routes
-    ├── [id]
-    │   └── page.tsx
     ├── blog
-    │   └── page.tsx
+    │   └── [id]
+    │       └── page.tsx
     └── page.tsx
 ```
 
@@ -189,48 +146,71 @@ export default () => {
 
 在组件中，可以通过 [useParams](/apis/app/runtime/router/router#useparams) 获取对应命名的参数。
 
-在 loader 中，params 会作为 [loader](/guides/basic-features/data/data-fetch#loader-函数) 的入参，通过 `params.xxx` 可以获取。
+```tsx
+import { useParams } from '@modern-js/runtime/router';
 
-### 动态可选路由
+function Blog() {
+  const { id } = useParams();
+  return <div>current blog ID is: {id}</div>;
+}
+export default Blog;
+```
+
+## 动态可选路由
 
 通过 `[$]` 命名的文件目录，生成的路由会作为动态可选路由。例如以下文件目录：
 
 ```bash
+.
 └── routes
-    ├── user
+    ├── blog
     │   └── [id$]
     │       └── page.tsx
-    ├── blog
-    │   └── page.tsx
     └── page.tsx
 ```
 
 `routes/user/[id$]/page.tsx` 文件会转为 `/user/:id?` 路由。`/user` 下的所有路由都会匹配到该路由，并且 `id` 参数可选存在。通常在区分**创建**与**编辑**时，可以使用该路由。
 
-在组件中，可以通过 [useParams](/apis/app/runtime/router/router#useparams) 获取对应命名的参数。
+```tsx
+import { useParams } from '@modern-js/runtime/router';
+
+function Blog() {
+  const { id } = useParams();
+  if (id) {
+    return <div>current blog ID is: {id}</div>;
+  }
+
+  return <div>create new blog</div>;
+}
+export default Blog;
+```
 
-在 loader 中，params 会作为 [loader](/guides/basic-features/data/data-fetch#loader-函数) 的入参，通过 `params.xxx` 可以获取。
 
-### 通配路由
+## 通配路由
 
-如果在 routes 目录下创建 `$.tsx` 文件，该文件会作为通配路由组件，当没有匹配的路由时，会渲染该路由组件。
+如果在某个子目录下存在 `$.tsx` 文件，该文件会作为通配路由组件，当没有匹配的路由时，会渲染该路由组件。
 
 :::note
-`$.tsx` 可以认为是一种特殊的 `page` 路由组件，当前目录下有 `layout` 组件时，`$.tsx`，会作为 `layout` 的子组件渲染。
+`$.tsx` 可以认为是一种特殊的 `<Page>` 组件，如果路由无法匹配，则 `$.tsx` 会作为 `<Layout>` 的子组件渲染。
+:::
+
+:::warning
+如果当前目录下不存在 `<Layout>` 组件时，则 `$.tsx` 不会生效。
 :::
 
 例如以下目录结构：
 
 ```bash
+.
 └── routes
     ├── blog
     │   ├── $.tsx
     │   └── layout.tsx
-    └── layout.tsx
+    ├── layout.tsx
     └── page.tsx
 ```
 
-当访问任何匹配不到的路径时(如 `/blog/a`)，都会渲染 `routes/blog/$.tsx` 组件，因为这里有 `layout.tsx`，渲染的 UI 如下：
+当你访问 `/blog/a` 时，无法匹配到任意路由，则页面会渲染 `routes/blog/$.tsx` 组件，路由的 UI 结构为：
 
 ```tsx
 <RootLayout>
@@ -246,16 +226,70 @@ export default () => {
 
 ```ts title="$.tsx"
 import { useParams } from '@modern-js/runtime/router';
-// 当 path 是 `/aaa/bbb` 时
-const params = useParams();
-params['*']; // => 'aaa/bbb'
+
+function Blog() {
+  // 当 path 是 `/blog/aaa/bbb` 时
+  const params = useParams();
+  console.log(params) // ---> { '*': 'aaa/bbb' }
+
+  return <div>current blog URL is {params["*"]}</div>;
+}
+export default Blog;
 ```
 
-`$.tsx` 可以加入到 `routes` 目录下的任意目录中，一个常见的使用示例是添加 `routes/$.tsx` 文件去定制任意层级的 404 内容。
+### 定制 404 页面
 
-### 无路径布局
+通配路由可以被添加到 `routes/` 目录下的任意子目录中，一种常见的使用场景是通过 `$.tsx` 文件去定制任意层级的 404 内容。
 
-当目录名以 \_\_ 开头时，对应的目录名不会转换为实际的路由路径，例如以下文件目录：
+例如你需要对所有未匹配到的路由，都展示一个 404 页面，可以添加 `routes/$.tsx` 文件：
+
+```bash
+.
+└── routes
+    ├── $.tsx
+    ├── blog
+    │   └── [id$]
+    │       └── page.tsx
+    ├── layout.tsx
+    └── page.tsx
+```
+
+```tsx
+function Page404() {
+  return <div>404 Not Found</div>;
+}
+export default Page404;
+```
+
+此时，当访问除了 `/` 或 `/blog/*` 以外的路由时，都会匹配到 `routes/$.tsx` 组件，展示 404 页面。
+
+## 路由句柄配置
+
+某些场景下，每个路由会拥有属于自己的数据，应用需要在其他组件中获取匹配到的路由的这些数据。一个常见的例子是在不居中获取到匹配路由的面包屑信息。
+
+Modern.js 提供了独立的约定，每个 `Layout`, `$` 或 `Page` 文件都可以定义一个自己的 `config` 文件，如 `page.config.ts`，该文件中我们约定了一个具名导出 `handle`，这个字段中你可以定义任意属性：
+
+```ts title="routes/page.config.ts"
+export const handle = {
+  breadcrumbName: 'profile',
+};
+```
+
+定义的这些属性可以通过 [`useMatches`](https://reactrouter.com/en/main/hooks/use-matches) hook 获取。
+
+```ts title="routes/layout.ts"
+export default () => {
+  const matches = useMatches();
+  const breadcrumbs = matches.map(
+    matchedRoute => matchedRoute?.handle?.breadcrumbName,
+  );
+  return <Breadcrumb names={breadcrumbs}></Breadcrumb>;
+};
+```
+
+## 无路径布局
+
+当目录名以 `__` 开头时，对应的目录名不会转换为实际的路由路径，例如以下文件目录：
 
 ```bash
 .
@@ -264,19 +298,19 @@ params['*']; // => 'aaa/bbb'
     │   ├── layout.tsx
     │   ├── login
     │   │   └── page.tsx
-    │   └── signup
+    │   └── sign
     │       └── page.tsx
     ├── layout.tsx
     └── page.tsx
 ```
 
-Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组件会作为 `login/page.tsx` 和 `signup/page.tsx` 的布局组件，但`__auth` 不会作为路由路径片段。
+Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组件会作为 `login/page.tsx` 和 `sign/page.tsx` 的布局组件，但`__auth` 不会作为路由路径片段出现在用户访问的 URL 中。
 
 当需要为某些类型的路由，做独立的布局，或是想要将路由做归类时，这一功能非常有用。
 
-### 无布局路径
+## 无布局路径
 
-有些情况下，项目需要较为复杂的路由，但这些路由又不存在独立的 UI 布局，如果像普通文件目录那边创建路由会导致目录层级较深。
+有些情况下，项目需要较为复杂的路由，但这些路由又不存在独立的 UI 布局，如果像普通文件目录那样创建路由会导致目录层级较深。
 
 因此 Modern.js 支持了通过 `.` 来分割路由片段，代替文件目录。例如，当需要 `/user/profile/2022/edit` 时，可以直接创建如下文件：
 
@@ -292,15 +326,93 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 
 ```tsx
 <RootLayout>
-  <UserProfileEdit /> // routes/user.profile.[id].edit/page.tsx
+  {/* routes/user.profile.[id].edit/page.tsx */}
+  <UserProfileEdit />
 </RootLayout>
 ```
 
-### Loading (Experimental)
+## 路由重定向
+
+某些应用中，可能需要根据用户的身份信息，或是其他数据条件，选择重定向到其他路由。在 Modern.js 中，你可以使用 [`Data Loader`](/guides/basic-features/data/data-fetch) 文件来获取数据，或是和传统 React 组件那样，在 `useEffect` 中请求数据。
+
+### 在 Data Loader 中重定向
+
+在任意的 `page.tsx` 同级目录中创建，`page.data.ts` 文件，这个文件就是该路由的 Data Loader。在 Data Loader 中，你可以通过调用 `redirect` API 来完成路由的重定向。
+
+```ts title="routes/user/page.data.ts"
+import { redirect } from '@modern-js/runtime/router';
+
+export const loader = () => {
+  const user = await getUser();
+  if (!user) {
+    return redirect('/login');
+  }
+  return null;
+};
+```
+
+### 在组件中重定向
+
+在组件内做重定向，则可以通过 `useNavigate` hook，示例如下：
+
+```ts title="routes/user/page.ts"
+import { useNavigate } from '@modern-js/runtime/router';
+import { useEffect } from 'react';
+
+export default () => {
+  const navigate = useNavigate();
+  useEffect(() => {
+    getUser().then(user => {
+      if (!user) {
+        navigate('/login');
+      }
+    });
+  });
+
+  return <div>Hello World</div>;
+};
+```
+
+## 错误处理
+
+`routes/` 下每一层目录中，开发者同样可以定义一个 `error.tsx` 文件，默认导出一个 `<ErrorBoundary>` 组件。当路由目录下存在该组件时，组件渲染出错会被 `ErrorBoundary` 组件捕获。
+
+`<ErrorBoundary>` 可以返回出错时的 UI 视图，当前层级未声明 `<ErrorBoundary>` 组件时，错误会向上冒泡到更上层的组件，直到被捕获或抛出错误。同时，当组件出错时，只会影响捕获到该错误的路由组件及子组件，其他组件的状态和视图不受影响，可以继续交互。
+
+{/* Todo API 路由 */}
+
+在 `<ErrorBoundary>` 组件内，可以使用 [useRouteError](/apis/app/runtime/router/router#userouteerror) 获取的错误的具体信息：
+
+```tsx
+import { useRouteError } from '@modern-js/runtime/router';
+
+const ErrorBoundary = () => {
+  const error = useRouteError();
+  return (
+    <div>
+      <h1>{error.status}</h1>
+      <h2>{error.message}</h2>
+    </div>
+  );
+};
+export default ErrorBoundary;
+```
+
+## Loading (Experimental)
 
-`routes/` 下每一层目录中，开发者可以创建 `loading.tsx` 文件，默认导出一个 `<Loading>` 组件。
+:::info Experimental
+此功能当前是实验性功能，后续 API 可能有调整。
+:::
+
+在约定式路由下， Modern.js 会根据路由，自动地对路由进行分片（每一个路由都作为单独的 JS Chunk 进行加载），当用户访问具体的路由时，再自动加载对应的分片。这样可以有效地减少首屏加载的时间。但这也带来了一个问题，当用户访问一个路由时，如果该路由对应的分片还未加载完成，就会出现白屏的情况。
+
+Modern.js 支持通过 `loading.tsx` 文件来解决这个问题，`routes/` 下每一层目录中，都可以创建 `loading.tsx` 文件，默认导出一个 `<Loading>` 组件。
+
+:::warning
+如果当前目录下不存在 `<Layout>` 组件时，则 `loading.tsx` 不会生效。为了保证用户体验，Modern.js 推荐每个应用添加根 Loading 组件。
+:::
 
-当路由目录下存在该组件和 `layout` 组件时，这一级子路由下所有的路由切换时，都会以该 `<Loading>` 组件作为 JS Chunk 加载时的 Fallback UI。例如以下文件目录：
+当路由目录下同时存在该组件和 `layout` 组件时，这一级路由下所有的子路由切换时，会先展示 `loading.tsx` 中导出的组件 UI，直到对应的 JS Chunk 加载完成。例如以下文件目录：
 
 ```bash
 .
@@ -314,9 +426,9 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
     └── page.tsx
 ```
 
-当定义 `loading.tsx` 时，就相当于以下布局：
+当定义 `loading.tsx` 时，当路由从 `/` 跳转到 `/blog`，或从 `/blog` 跳转到 `/blog/123` 时，如果路由对应的 JS Chunk 还未加载，都会先展示 `loading.tsx` 中导出的组件 UI。相当于最终的 UI 结构如下：
 
-```tsx title=当路由为"/"时
+```tsx title=当路由为 "/" 时
 <Layout>
   <Suspense fallback={<Loading />}>
     <Page />
@@ -324,7 +436,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 </Layout>
 ```
 
-```tsx title=当路由为"/blog"时
+```tsx title=当路由为 "/blog" 时
 <Layout>
   <Suspense fallback={<Loading />}>
     <BlogPage />
@@ -332,7 +444,7 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 </Layout>
 ```
 
-```tsx title=当路由为"/blog/123"时
+```tsx title=当路由为 "/blog/123" 时
 <Layout>
   <Suspense fallback={<Loading />}>
     <BlogIdPage />
@@ -340,72 +452,42 @@ Modern.js 会生成 `/login` 和 `/sign` 两条路由，`__auth/layout.tsx` 组
 </Layout>
 ```
 
-:::info
-当目录的 Layout 组件不存在时，该目录下的 Loading 组件也不会生效。
-Modern.js 建议必须有根 Layout 和根 Loading。
-
-:::
-
-当路由从 `/` 跳转到 `/blog` 时，如果 `blog/page` 组件的 JS Chunk 还未加载，则会先展示 `loading.tsx` 中导出的组件 UI。
+## 预加载
 
-同理，当路由从 `/` 或者 `/blog` 跳转到 `/blog/123` 时，如果 `blog/[id]/page` 组件的 JS Chunk 还未加载，也会先展示 `loading.tsx` 中导出的组件 UI。
+大多数切换路由时白屏的情况，都可以通过定义 `<Loading>` 组件来优化体验。Modern.js 也支持在 `<Link>` 组件上定义 `prefetch` 属性，提前对静态资源和数据进行加载。
 
-### 路由重定向
+对于有更高性能要求的应用，预加载可以进一步提升用户体验，减少展示 `<Loading>` 组件的时间：
 
-可以使用 [`Data Loader`](/guides/basic-features/data/data-fetch) 文件做路由的重定向。如有文件 `routes/user/page.tsx`，想对这个文件对应的路由做重定向，可以创建 `routes/user/page.data.ts` 文件：
-
-```ts title="routes/user/page.data.ts"
-import { redirect } from '@modern-js/runtime/router';
-
-export const loader = () => {
-  const user = await getUser();
-  if (!user) {
-    return redirect('/login');
-  }
-  return null;
-};
+```tsx
+<Link prefetch="intent" to="page">
 ```
 
-在组件内做重定向，则可以通过 `useNavigate` hook，示例如下：
+:::tip
 
-```ts title="routes/user/page.ts"
-import { useNavigate } from '@modern-js/runtime/router';
-
-export default () => {
-  const navigate = useNavigate();
-  navigate('/login');
-};
-```
+- 该功能目前仅在 Webpack 项目中支持，Rspack 项目暂不支持。
+- 对数据的预加载目前只会预加载 SSR 项目中 [Data Loader](/guides/basic-features/data/data-fetch) 中返回的数据。
 
-### 错误处理
+:::
 
-`routes/` 下每一层目录中，开发者同样可以定义一个 `error.tsx` 文件，默认导出一个 `<ErrorBoundary>` 组件。
+`prefetch` 属性有三个可选值：
 
-当有路由目录下存在该组件时，组件渲染出错会被 `ErrorBoundary` 组件捕获。当目录未定义 `layout.tsx` 文件时，`<ErrorBoundary>` 组件不会生效。
+- `none`， 默认值，不会做 prefetch，没有任何额外的行为。
+- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 Data Loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
+- `render`，当 `<Link>` 组件渲染时，就会加载对应的分片和 Data Loader 中定义的数据。
 
-`<ErrorBoundary>` 可以返回出错时的 UI 视图，当前层级未声明 `<ErrorBoundary>` 组件时，错误会向上冒泡到更上层的组件，直到被捕获或抛出错误。同时，当组件出错时，只会影响捕获到该错误的路由组件及子组件，其他组件的状态和视图不受影响，可以继续交互。
+:::details 值为 render 和不做路由分片的区别
+- `render` 加载路由分片的时机是可控的，只有在 `<Link>` 组件进入视窗时才触发，可以通过控制 `<Link>` 组件的渲染位置来控制分片加载时机。
+- `render` 仅在空闲时对静态资源进行加载，不占用重要模块的加载时间。
+- 除了预加载路由分片，`render` 在 SSR 项目中还会发起数据预取。
 
-{/* Todo API 路由 */}
+:::
 
-在 `<ErrorBoundary>` 组件内，可以使用 [useRouteError](/apis/app/runtime/router/router#userouteerror) 获取的错误的具体信息：
 
-```tsx
-import { useRouteError } from '@modern-js/runtime/router';
-const ErrorBoundary = () => {
-  const error = useRouteError();
-  return (
-    <div>
-      <h1>{error.status}</h1>
-      <h2>{error.message}</h2>
-    </div>
-  );
-};
-export default ErrorBoundary;
-```
+## 运行时配置
 
-### 运行时配置
+{/* Todo 移到动运行时配置章节 */}
 
-在每个根 `Layout` 组件中(`routes/layout.ts`)，可以动态地定义运行时配置：
+在根 `<Layout>` 组件中（`routes/layout.ts`），可以动态地定义运行时配置：
 
 ```tsx title="src/routes/layout.tsx"
 // 定义运行时配置
@@ -427,7 +509,9 @@ export const config = (): AppConfig => {
 };
 ```
 
-### 渲染前的钩子
+## 渲染前的钩子
+
+{/* Todo 移到动运行时配置章节 */}
 
 在有些场景下，需要在应用渲染前做一些操作，可以在 `routes/layout.tsx` 中定义 `init` 钩子，`init` 在客户端和服务端均会执行，基本使用示例如下：
 
@@ -490,91 +574,22 @@ export const init = (context: RuntimeContext) => {
 };
 ```
 
-### 预加载
-
-在约定式路由下， Modern.js 会根据路由，自动地对路由进行分片。当用户访问具体的路由时，会自动加载对应的分片，这样可以有效地减少首屏加载的时间。但这也带来了一个问题，当用户访问一个路由时，如果该路由对应的分片还未加载完成，就会出现白屏的情况。
-这种情况下你可以通过定义 `Loading` 组件，在静态资源加载完成前，展示一个自定义的 `Loading` 组件。
-
-为了进一步提升用户体验，减少 loading 的时间，Modern.js 支持在 Link 组件上定义 `prefetch` 属性，可以提前对静态资源和数据进行加载：
-
-```tsx
-<Link prefetch="intent" to="page">
-```
-
-:::info
-
-- 该功能目前仅在 Webpack 项目中支持，Rspack 项目暂不支持。
-- 对数据的预加载目前只会预加载 SSR 项目中 [Data Loader](/guides/basic-features/data/data-fetch) 中返回的数据。
-
-:::
-
-`prefetch` 属性有三个可选值：
-
-- `none`， 默认值，不会做 prefetch，没有任何额外的行为。
-- `intent`，这是我们推荐大多数场景下使用的值，当你把鼠标放在 Link 上时，会自动开始加载对应的分片和 Data Loader 中定义的数据，当鼠标移开时，会自动取消加载。在我们的测试中，即使是快速点击，也能减少大约 200ms 的加载时间。
-- `render`，当 Link 组件渲染时，就会加载对应的分片和 Data Loader 中定义的数据。
-
-#### 常见问题
-
-1. 使用 `render` 和不根据路由做静态资源分片的区别？
-
-- 使用 `render` 可以指定哪些路由在首屏时，进行加载，同时你可以通过对渲染的控制，仅当 `Link` 组件进入到可视区域时，才对 `Link` 组件进行渲染。
-- 使用 `render`，仅在空闲时对静态资源进行加载，不会与首屏静态资源抢占网络。
-- 在 SSR 场景下，也会对数据进行预取。
-
 import Motivation from '@site-docs/components/convention-routing-motivation';
 
 <Motivation />
 
-import Practice from '@site-docs/components/routes-practice';
+## 常见问题
 
-<Practice />
+1. 为什么要提供 `@modern-js/runtime/router` 来导出 React Router API ?
 
-## 自控式路由
+可以发现，在文档中所有的代码用例都是使用 `@modern-js/runtime/router` 包导出的 API，而不是直接使用 React Router 包导出的 API。那两者有什么区别呢？
 
-以 `src/App.tsx` 为约定的入口，Modern.js 不会对路由做额外的操作，开发者可以自行使用 [React Router 6](https://reactrouter.com/en/main) 的 API 进行开发，例如：
+首先，在 `@modern-js/runtime/router` 中导出的 API 和 React Router 包的 API 是完全一致的，如果某个 API 使用出现问题，请先检查 React Router 的文档和 Issues。
 
-```ts title="src/App.tsx"
-import { BrowserRouter, Route, Routes } from '@modern-js/runtime/router';
-
-export default () => {
-  return (
-    <BrowserRouter>
-      <Routes>
-        <Route index element={<div>index</div>} />
-        <Route path="about" element={<div>about</div>} />
-      </Routes>
-    </BrowserRouter>
-  );
-};
-```
+在使用约定式路由的情况下，务必使用 `@modern-js/runtime/router` 中的 API，不直接使用 React Router 的 API。因为 Modern.js 内部会安装 React Router，如果应用中使用了 React Router 的 API，可能会导致两个版本的 React Router 同时存在，出现不符合预期的行为。
 
 :::note
-Modern.js 默认对约定式路由做了一系列资源加载及渲染上的优化，并且提供了开箱即用的 SSR 能力。而在使用自控路由时，这些能力都需要开发者自行封装。我们推荐开发者使用约定式路由。
+如果应用中必须直接使用 React Router 包的 API，例如部分路由行为被封装在统一的 npm 包中，那应用可以通过设置 [`source.alias`](/configure/app/source/alias)，将 `react-router` 和 `react-router-dom` 统一指向项目的依赖，避免两个版本的 React Router 同时存在的问题。
 :::
 
-## 其他路由方案
-
-默认情况下，Modern.js 会开启内置的路由方案，即 React Router。
-
-```js
-export default defineConfig({
-  runtime: {
-    router: true,
-  },
-});
-```
-
-如上述配置，当开启 [`runtime.router`](/configure/app/runtime/router) 配置时，Modern.js 会从 `@modern-js/runtime/router` 命名空间导出 React Router 的 API 供开发者使用，保证开发者和 Modern.js 中使用同一份代码，并自动根据 router 配置包裹 `Provider` 组件。另外，这种情况下，React Router 的代码会被打包到 JS 产物中。
-
-如果项目已经有自己的路由方案，或者不需要使用客户端路由，可以关闭这个功能。
-
-```js
-export default defineConfig({
-  runtime: {
-    router: false,
-  },
-});
-```
 
-如上述配置， 如果关闭了 [`runtime.router`](/configure/app/runtime/router) 配置，并直接使用 `react-router-dom` 进行项目路由管理时，还需要根据 React Router 文档自行包裹 `Provider`。