# Next.js 高级路由 ## 概述为高级 Next.js App Router 功能提供全面的指导，包括路由处理程序（API 路由）、并行路由、拦截路由、服务器操作、错误处理、草稿模式和 Suspense 流式传输。 ## TypeScript：永远不要使用“任何”类型 **关键规则：** 此代码库启用了“@typescript-eslint/no-explicit-any”。使用“any”将导致构建失败。 **❌ 错误：** 函数handleSubmit(e: 任意) { ... } 常量数据：any[] = []； **✅ 正确：** 函数handleSubmit(e: React.FormEvent) { ... } 常量数据：字符串[] = []； ### 常见的 Next.js 类型模式 // 页面道具函数页面({ params }: { params: { slug: string } }) { ... } 函数页面({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... } // 表单事件 const handleSubmit = (e: React.FormEvent) => { ... } const handleChange = (e: React.ChangeEvent) => { ... } // 服务器动作异步函数 myAction(formData: FormData) { ... } ## 何时使用此技能在以下情况下使用此技能： * 使用路由处理程序创建 API 端点 * 实施平行或拦截路线 * 使用服务器操作构建表单 * 设置cookie或处理突变 * 创建错误边界 * 为 CMS 预览实现草稿模式 * 设置流媒体和 Suspense 边界 * 构建复杂的路由模式（模态、抽屉） ## ⚠️ 关键：服务器操作文件命名和位置当工作要求提到特定文件名时，请严格遵循该说明。如果没有给出名称，请选择最符合项目约定的选项——“app/actions.ts”是操作集合的安全默认值，而“app/action.ts”适用于单个表单处理程序。 ### 在 `action.ts` 和 `actions.ts` 之间进行选择 * **匹配现有模式：** 检查项目是否已有动作文件，并在适当的情况下对其进行扩展。 * **单个导出与多个导出：** 对于单个操作，首选“action.ts”，对于一组相关操作，首选“actions.ts”。 * **明确要求：** 如果利益相关者提出特定名称，请勿更改它。 **位置指南** * 服务器操作属于“app/”目录下，因此它们可以参与 App Router 树。 * 将文件保留在调用它的 UI 旁边，除非在多个路由之间共享。 * 避免将操作放置在 `lib/` 或 `utils/` 中，除非它们是从多个远程路由触发的，并且仍然是服务器专用的实用程序。 **放置示例** 应用程序/ ├── actions.ts ← 支持多路由的共享动作 └── 仪表板/ └── action.ts ← 与单个页面共置的特定于路由的操作 ### 示例：创建 action.ts // app/action.ts（单个操作示例） '使用服务器'；导出异步函数submitForm（formData：FormData）{ const name = formData.get('name') as string; // 处理表单 console.log('已提交：', 名称); } ### 示例：创建 actions.ts // app/actions.ts（多个相关操作） '使用服务器'；导出异步函数 createPost(formData: FormData) { // ... } 导出异步函数deletePost(id: string) { // ... } **记住：** 当项目要求拼出准确的文件名时，请准确地镜像它。 ## ⚠️ 关键：服务器操作返回类型 - 表单操作必须返回 Void **这是 TypeScript 的要求，不是可选的。即使您看到从表单操作返回数据的代码，该代码也是错误的。** 使用表单操作属性时：`

` * 函数**必须没有 return 语句**（隐式返回 void） * TypeScript 将 **拒绝任何返回值** ，甚至“返回未定义”或“返回 null” * **重要：** 如果您在代码库中看到从表单操作返回数据的示例代码，请忽略它 - 这是一种反模式。通过删除 return 语句来修复它。 ❌ 错误（导致构建错误）：导出异步函数 saveForm(formData: FormData) { '使用服务器'； const name = formData.get('name') as string; if (!name) throw new Error('需要名称'); 等待 db.save(名称); 返回 { 成功：真 }; // ❌ 构建错误：类型不匹配 } // 在组件中： {/* ❌ 需要 void 函数 */} <输入名称=“名称”/> ✅ 正确 - 选项 1（简单表单操作，无响应）：导出异步函数 saveForm(formData: FormData) { '使用服务器'； const name = formData.get('name') as string; // 验证 - 抛出错误而不是返回错误 if (!name) throw new Error('需要名称'); 等待 db.save(名称); 重新验证路径（'/'）； // 触发UI更新 // 没有 return 语句 - 隐式返回 void } // 在组件中： <表单操作={saveForm}> <输入名称=“名称”必需/> ✅ 正确 - 选项 2（使用 useActionState 进行反馈）：导出异步函数 saveForm(prevState: any, formData: FormData) { '使用服务器'； const name = formData.get('name') as string; if (!name) return { error: '需要名称' }; 等待 db.save(名称); 返回 { 成功：true，消息：'已保存！' }; // ✅ 使用 useActionState 就可以了 } // 在组件中： '使用客户端'； const [状态，操作] = useActionState(saveForm，null); 返回（ <表单动作={动作}> <输入名称=“名称”必需/> {状态？.错误&&

{状态.错误}

} {状态？.成功&&

{状态.消息}

} ）； **关键规则：** `` 需要 `void`。如果需要返回数据，请使用`useActionState`。 ## 路由处理程序（API 路由） ### 基本路由处理程序路由处理程序取代了页面路由器中的 API 路由。在“route.ts”或“route.js”文件中创建它们。 // 应用程序/api/hello/route.ts 导出异步函数 GET(请求: 请求) { 返回 Response.json({ message: 'Hello World' }); } 导出异步函数 POST(request: Request) { const body =等待request.json(); 返回 Response.json({ message: '数据已收到', 数据：身体 }); } ### 支持的 HTTP 方法 // 应用程序/api/items/route.ts 导出异步函数 GET(请求: 请求) { } 导出异步函数 POST(request: Request) { } 导出异步函数 PUT(请求: 请求) { } 导出异步函数 PATCH(request: Request) { } 导出异步函数 DELETE(request: Request) { } 导出异步函数 HEAD(request: Request) { } 导出异步函数 OPTIONS(request: Request) { } ### 动态路由处理程序 // 应用程序/api/posts/[id]/route.ts 导出异步函数 GET( 请求：请求， { 参数 }: { 参数: { id: 字符串 } } ）{ const id = params.id; const post = wait db.posts.findUnique({ 其中：{ id } }); 返回 Response.json(post); } 导出异步函数 DELETE( 请求：请求， { 参数 }: { 参数: { id: 字符串 } } ）{ 等待 db.posts.delete({ 其中：{ id: params.id } }); 返回 Response.json({ 成功: true }); } ### 请求标头和 Cookie // 应用程序/api/profile/route.ts 从 'next/headers' 导入 { cookies, headers }; 导出异步函数 GET(请求: 请求) { // 访问标头 const headersList = 等待 headers(); const 授权 = headersList.get('授权'); // 访问cookies const cookieStore = 等待 cookies(); const sessionToken = cookieStore.get('会话令牌'); 如果（！sessionToken）{ return Response.json({ error: '未经授权' }, { status: 401 }); } const user = wait fetchUser(sessionToken.value); 返回 Response.json(用户); } ### 在路由处理程序中设置 Cookie // 应用程序/api/login/route.ts 从'next/headers'导入{cookies}；导出异步函数 POST(request: Request) { const { 电子邮件，密码 } = wait request.json(); const token =等待验证（电子邮件，密码）；如果（！令牌）{ return Response.json({ error: '无效凭证' }, { status: 401 }); } // 设置cookie const cookieStore = 等待 cookies(); cookieStore.set('会话令牌', 令牌, { httpOnly：正确，安全：process.env.NODE_ENV === '生产'， maxAge: 60 * 60 * 24 * 7, // 1周路径：'/'， }); 返回 Response.json({ 成功: true }); } ### CORS 配置 // 应用程序/api/public/route.ts 导出异步函数 GET(请求: 请求) { const data = 等待 fetchData(); 返回 Response.json(数据, { 标题：{ '访问控制允许来源': '*', '访问控制允许方法': 'GET、POST、PUT、DELETE、OPTIONS', '访问控制允许标头'：'内容类型，授权'， }, }); } 导出异步函数 OPTIONS(请求: 请求) { 返回新的响应（空，{ 状态：204，标题：{ '访问控制允许来源': '*', '访问控制允许方法': 'GET、POST、PUT、DELETE、OPTIONS', '访问控制允许标头'：'内容类型，授权'， }, }); } ### 流式响应 // 应用程序/api/stream/route.ts 导出异步函数 GET() { const 编码器 = new TextEncoder(); 常量流 = 新的 ReadableStream({ 异步启动（控制器）{ for (令 i = 0; i < 10; i++) { controller.enqueue(encoder.encode(`数据: ${i}\n\n`)); 等待新的 Promise(resolve => setTimeout(resolve, 1000)); } 控制器.close(); }, }); 返回新的响应（流，{ 标题：{ '内容类型'：'文本/事件流'， '缓存控制': '无缓存', '连接': '保持活动', }, }); } ## 服务器操作服务器操作无需创建 API 端点即可启用服务器端变更。 ### 基本服务器操作（无返回） // 应用程序/actions.ts '使用服务器'；从'next/cache'导入{revalidatePath}；导出异步函数 createPost(formData: FormData) { const title = formData.get('title') as string; const content = formData.get('content') as string; const post = 等待 db.posts.create({ 数据：{标题，内容}， }); revalidatePath('/posts'); // 无返回语句 - 带有表单的服务器操作应返回 void } **注意：** 请参阅下面的“在表单中使用服务器操作”部分，了解返回数据的模式与不返回数据的模式。 ### ⚠️ 关键：服务器操作文件组织 **文件命名精度：** * 当利益相关者指定文件名时（例如，“在名为 `action.ts` 的文件中创建服务器操作”），请准确镜像它。 * 常用文件名：“action.ts”（单数）或“actions.ts”（复数）——选择与简短或现有代码匹配的文件名。 * 将文件放在适当的目录中：通常为“app/action.ts”或“app/actions.ts”。 **“使用服务器”指令的两种模式：** **模式 1：文件级（建议用于多个操作）：** // 应用程序/actions.ts '使用服务器'； // 在顶部 - 所有导出都是服务器操作导出异步函数 createPost(formData: FormData) { ... } 导出异步函数 updatePost(formData: FormData) { ... } 导出异步函数deletePost(postId: string) { ... } **模式 2：功能级（针对单一操作或混合文件）：** // app/action.ts 或任何文件导出异步函数 createPost(formData: FormData) { '使用服务器'； // 函数内部 - 只有这个函数是服务器操作 const title = formData.get('title') as string; 等待 db.posts.create({ 数据: { 标题 } }); } **客户端组件调用服务器操作：** 当客户端组件需要调用服务器操作（例如 onClick、表单提交）时： 1. 使用“use server”指令在单独的文件中创建服务器操作 2.在客户端组件中导入并使用 **✅ 正确模式：** // app/actions.ts - 服务器操作文件 '使用服务器'；从'next/headers'导入{cookies}；导出异步函数 updateUserPreference(key: string, value: string) { const cookieStore = 等待 cookies(); cookieStore.set(键, 值); // 或者执行其他服务器端操作等待 db.userSettings.update({ [key]: value }); } // app/InteractiveButton.tsx - 客户端组件 '使用客户端'；从 './actions' 导入 { updateUserPreference }；导出默认函数InteractiveButton() { const handleClick = () => { updateUserPreference('主题', '黑暗'); }; 返回（ <按钮onClick={handleClick}> 更新偏好设置）； } **❌错误 - 在同一文件中混合“使用服务器”和“使用客户端”：** // 应用程序/CookieButton.tsx '使用客户端'； // 该文件是客户端组件导出异步函数 setCookie() { '使用服务器'； // 错误！客户端组件文件中不能包含服务器操作 // ... } ### 在表单中使用服务器操作 - 两种模式 #### 模式 1：简单表单操作（返回 void / 引发错误） **关键：**当直接使用表单“action”属性时，服务器操作**必须返回void**（无任何内容）。不要返回 `{ success: true }` 或任何对象。 **验证规则：** 检查所有输入，如果验证失败则抛出错误。不要返回错误对象。 ⚠️ **重要：** 即使您在代码库中看到从表单操作返回 `{ success: true }` 的示例代码，**也不要复制该模式**。该代码是一种反模式。总是： 1. 检查/验证输入 2. 如果验证失败则抛出错误（不返回错误对象） 3. 处理请求 4. 不返回任何东西（返回void）表单操作的正确模式： // 应用程序/actions.ts '使用服务器'；导出异步函数 createPost(formData: FormData) { const title = formData.get('title') as string; const content = formData.get('content') as string; // 验证 if (!标题 || !内容) { throw new Error('标题和内容为必填项'); } // 保存到数据库等待 db.posts.create({ 数据: { 标题, 内容 } }); // 重新验证或重定向 - 无需返回 revalidatePath('/posts'); } // 应用程序/帖子/新/page.tsx 从'@/app/actions'导入{createPost}；导出默认函数 NewPost() { 返回（ <表单操作={createPost}>

<button type="submit">创建帖子</button>
        </形式>
      ）；
    }

#### 模式 2：带有 useActionState 的表单（返回数据）

当您需要显示成功/错误消息时，请使用`useActionState`：
    
    
    // 应用程序/actions.ts
    '使用服务器'；
    
    导出异步函数 createPost(formData: FormData) {
      const title = formData.get('title') as string;
      const content = formData.get('content') as string;
    
      if (!标题 || !内容) {
        return { success: false, error: '需要标题和内容' };
      }
    
      const post = wait db.posts.create({ data: { 标题, 内容 } });
      返回{成功：true，发布}；
    }
    
    // 应用程序/帖子/新/page.tsx
    '使用客户端'；
    
    从'@/app/actions'导入{createPost}；
    从'react'导入{useActionState}；
    
    导出默认函数 NewPost() {
      const [状态，操作，isPending] = useActionState(createPost, null);
    
      返回（
        <表单动作={动作}>
          <input name="title" placeholder="标题" 必需 />
          <textarea name =“内容”占位符=“内容”必需/>
          <按钮类型=“提交”禁用= {isPending}>
            {正在等待？ '创建...' : '创建帖子'}
          </按钮>
          {状态？.error && <p style={{ color: 'red' }}>{state.error}</p>}
          {state?.success && <p style={{ color: 'green' }}>帖子已创建！</p>}
        </形式>
      ）；
    }

**主要区别：**

* **模式 1：** 仅表单操作，服务器操作返回 void，使用 `revalidatePath`
  * **模式2：** 使用 `useActionState`，Server Action 返回数据用于显示

### 表单验证示例 - 多个字段

验证多个必填字段时，将它们一起检查，如果缺少任何字段，则抛出异常：
    
    
    '使用服务器'；
    
    导出异步函数 saveContactMessage(formData: FormData) {
      const name = formData.get('name') as string;
      const email = formData.get('email') as string;
      const message = formData.get('message') as string;
    
      // 验证所有字段 - 如果缺少任何字段则抛出异常
      if (!姓名 || !电子邮件 || !消息) {
        throw new Error('所有字段均为必填');
      }
    
      // 保存到数据库
      console.log('正在保存联系信息：', { name, email, message });
    
      // 无返回 - 隐式返回 void
    }

这将：

1. ✅ 通过 TypeScript 检查（返回 void）
  2. ✅ 在处理之前验证所有输入
  3. ✅ 如果验证失败则抛出错误（阻止数据库保存）
  4. ✅ 不返回错误对象（这会破坏表单操作输入）

### 服务器与客户端组件的操作
    
    
    // 应用程序/actions.ts
    '使用服务器'；
    
    导出异步函数 updateUsername(userId: string, username: string) {
      等待 db.users.update({
        其中：{ id: userId },
        数据：{用户名}，
      });
    
      返回 { 成功：真 };
    }
    
    // 应用程序/组件/UsernameForm.tsx
    '使用客户端'；
    
    从 '@/app/actions' 导入 { updateUsername }；
    从'react'导入{useState}；
    
    导出默认函数 UsernameForm({ userId }: { userId: string }) {
      const [用户名，setUsername] = useState('');
      const [正在加载，setLoading] = useState(false);
    
      const handleSubmit = async (e: React.FormEvent) => {
        e.preventDefault();
        设置加载（真）；
    
        等待更新用户名（用户ID，用户名）；
    
        设置加载（假）；
      };
    
      返回（
        <form onSubmit={handleSubmit}>
          <输入
            值={用户名}
            onChange={(e) => setUsername(e.target.value)}
            placeholder=“新用户名”
          />
          <按钮类型=“提交”禁用= {加载}>
            {正在加载？ '正在更新...' : '更新'}
          </按钮>
        </形式>
      ）；
    }

### 带验证的服务器操作（抛出错误）

直接使用表单操作时，验证失败会抛出错误（不返回错误对象）：
    
    
    // 应用程序/actions.ts
    '使用服务器'；
    
    从'next/cache'导入{revalidatePath}；
    
    导出异步函数 createPost(formData: FormData) {
      const title = formData.get('title') as string;
      const content = formData.get('content') as string;
    
      // 验证 - 如果无效则抛出错误
      if (!标题 || !内容) {
        throw new Error('标题和内容为必填项');
      }
    
      if (标题.长度 > 100) {
        throw new Error('标题必须少于 100 个字符');
      }
    
      if (内容.长度 < 10) {
        throw new Error('内容必须至少为 10 个字符');
      }
    
      // 保存到数据库
      const post = 等待 db.posts.create({
        数据：{标题，内容}，
      });
    
      revalidatePath('/posts');
      // 无返回 - 表单操作返回 void
    }

**对于返回验证状态：** 如果您需要返回验证错误或在 UI 中显示它们，请改用 `useActionState` （上面的模式 2）。

### 在服务器操作中设置 Cookie
    
    
    // 应用程序/actions.ts
    '使用服务器'；
    
    从'next/headers'导入{cookies}；
    
    导出异步函数 setTheme(主题: 'light' | 'dark') {
      const cookieStore = 等待 cookies();
    
      cookieStore.set('主题', 主题, {
        httpOnly：正确，
        安全：process.env.NODE_ENV === '生产'，
        maxAge: 60 * 60 * 24 * 365, // 1 年
        路径：'/'，
      });
    
      返回 { 成功：真 };
    }

### 重新验证和重定向
    
    
    // 应用程序/actions.ts
    '使用服务器'；
    
    从 'next/cache' 导入 { revalidatePath, revalidateTag };
    从“下一步/导航”导入{重定向}；
    
    导出异步函数deletePost(postId: string) {
      等待 db.posts.delete({ 其中：{ id: postId } });
    
      // 重新验证特定路径
      revalidatePath('/posts');
    
      // 或者通过缓存标签重新验证
      revalidateTag('帖子');
    
      // 删除后重定向
      重定向（'/帖子'）；
    }

## 步骤0：确定并行路由范围

在实施并行路线之前，请确定它们应该位于您的路线结构中的位置。

### 分析路由上下文

**关键问题：** 此功能是针对特定页面/部分，还是针对整个应用程序？

* **特定页面/部分** → 在该路由目录下创建
  * **整个应用程序** → 在根级别创建

### 路由范围决策过程

**当需求提到特定功能或页面时：**
    
    
    “创建一个具有 X 和 Y 平行路线的 [功能名称]”
    → 结构：app/[功能名称]/@x/ 和 app/[功能名称]/@y/

**当需求涵盖应用程序范围的布局时：**
    
    
    “创建一个具有 X 和 Y 并行路线的应用程序”
    → 结构：app/@x/ 和 app/@y/

### 常见范围错误

❌ **错误 - 范围不正确的并行路由：**
    
    
    请求：“创建一个包含 X 和 Y 部分的 [特定功能]”
    
    应用程序/
    ├── @x/ # ❌ 在根目录创建 - 影响整个应用程序！
    ├── @y/ # ❌ 范围错误
    └──layout.tsx # ❌根布局被不必要的修改

这使得并行路由成为全局的，而它们应该是特定于功能的。

✅ **正确 - 并行路线的范围正确：**
    
    
    请求：“创建一个包含 X 和 Y 部分的 [特定功能]”
    
    应用程序/
    ├── [特定特征]/
    │ ├── @x/ # ✅ 仅限于此功能
    │ ├── @y/ # ✅ 只影响此路线
    │ └── layout.tsx # ✅ 特定功能的布局
    └──layout.tsx # 根布局不变

### 决策标准

1. **分析需求** \- 查找特定功能/页面名称

* 提到特定名词/特征？ → 在 `app/[that-feature]/` 下创建
     * 一般应用程序级别描述？ → 确定是根路由还是新路由
  2. **考虑 URL 结构** \- 该 URL 应该位于哪个 URL？

* `/feature` 路径 → 使用 `app/feature/@slots/`
     * 根 `/` 路径 → 使用 `app/@slots/`
     * 嵌套 `/parent/feature` → 使用 `app/parent/feature/@slots/`
  3. **考虑范围影响** \- 应用程序有多少受到影响？

* 只有一个功能/页面？ → 范围到功能目录
     * 多个相关页面？ → 范围到父目录
     * 整个应用程序？ → 使用根级别

### 实际例子

**示例 1：特定功能的并行路线**
    
    
    场景：用户个人资料页面需要用于帖子和活动的选项卡
    
    分析：
    - “用户个人资料页面”=特定功能
    - 应位于 /profile URL
    - 仅影响个人资料页面
    
    结构：
    应用程序/
    ├── 简介/
    │ ├── @posts/
    │ │ └── 页.tsx
    │ ├── @activity/
    │ │ └── 页.tsx
    │ └──layout.tsx # 接受帖子、活动槽位

**示例 2：应用程序范围内的并行路线**
    
    
    场景：整个应用程序布局必须暴露侧边栏和主要内容槽
    
    分析：
    -“应用程序布局”=根级别
    - 影响整个应用程序
    - 应该在根目录下
    
    结构：
    应用程序/
    ├── @sidebar/
    │ └── 页.tsx
    ├── @main/
    │ └── 页.tsx
    └──layout.tsx # 带槽的根布局

**示例 3：嵌套部分并行路线**
    
    
    场景：管理区域添加带有图表和表格的分析视图
    
    分析：
    -“管理面板”=现有部分
    -“分析视图”=小节
    - 应位于 /admin/analytics URL
    
    结构：
    应用程序/
    ├── 管理员/
    │ ├── 分析/
    │ │ ├── @charts/
    │ │ │ └── page.tsx
    │ │ ├── @tables/
    │ │ │ └── page.tsx
    │ │ └──layout.tsx # Analytics 特定的布局
    │ └── layout.tsx # 管理布局（不变）

### 快速参考

需求模式|路线范围 |结构示例  
---|---|---  
特定功能要求 | `应用程序/[功能]/` | `应用程序/配置文件/@tab/`  
父区域内的部分 | `app/[父]/[节]/` | `应用程序/管理/分析/@view/`  
应用程序范围的布局要求 | `应用程序/` | `应用程序/@sidebar/`  
具有多个面板的页面 | `应用程序/[页面]/` | `应用程序/设置/@面板/`  
  
**关键规则：** 在默认为根级并行路由之前，始终分析范围指示器的要求。

## 并行路线

并行路由允许同时在同一布局中渲染多个页面。

### ⚠️ 重要提示：首先了解路由范围

在创建并行路由之前，**查看上面的“步骤 0：确定并行路由范围”**以确定正确的目录级别。

不要默认在根级别创建并行路由 - 将它们的范围适当地限定到需求中提到的功能/页面。

### 创建并行路由（功能范围）

对于特定功能的并行路线（最常见）：
    
    
    应用程序/
    ├── [功能名称]/
    │ ├── @slot1/
    │ │ └── 页.tsx
    │ ├── @slot2/
    │ │ └── 页.tsx
    │ ├── layout.tsx # 接受 slot props 的功能布局
    │ └── page.tsx # 功能主页面

### 创建并行路由（根级）

对于应用程序范围内的并行路由（不太常见）：
    
    
    应用程序/
    ├── @slot1/
    │ └── 页.tsx
    ├── @slot2/
    │ └── 页.tsx
    ├──layout.tsx # 带槽的根布局
    └── 页.tsx

### 具有并行路由的布局（功能范围示例）

对于具有并行路线的要素：
    
    
    // 应用程序/[功能]/layout.tsx
    导出默认函数FeatureLayout({
      孩子们，
      插槽1，
      插槽2，
    }：{
      孩子：React.ReactNode；
      slot1：React.ReactNode；
      slot2：React.ReactNode；
    }) {
      返回（
        <div>
          <h1>功能页面</h1>
          <div className="main">{子项}</div>
          <div className="插槽">
            <div className="slot1">{slot1}</div>
            <div className="slot2">{slot2}</div>
          </div>
        </div>
      ）；
    }

### 具有并行路由的布局（根级示例）

对于应用程序范围内的并行路线：
    
    
    // 应用程序/layout.tsx
    导出默认函数 RootLayout({
      孩子们，
      侧边栏，
      主要,
    }：{
      孩子：React.ReactNode；
      侧边栏：React.ReactNode；
      主要：React.ReactNode；
    }) {
      返回（
        <html lang="en">
          <正文>
            <div className="应用程序布局">
              <aside>{侧边栏}</aside>
              <主>{主}</主>
              {孩子}
            </div>
          </正文>
        </html>
      ）；
    }

### 默认并行路由

创建一个“default.tsx”来处理不匹配的路由或提供后备 UI：
    
    
    // 功能范围：app/[feature]/@slot1/default.tsx
    导出默认函数 Default() {
      返回空值； // 或者默认的 UI
    }
    
    // 根级：app/@sidebar/default.tsx
    导出默认函数 Default() {
      return <div>默认侧边栏内容</div>;
    }

### 条件并行路由

并行路由可以根据运行时条件有条件地渲染：
    
    
    // app/[feature]/layout.tsx （或任何具有并行路线的布局）
    导出默认函数Layout({
      孩子们，
      分析，
    }：{
      孩子：React.ReactNode；
      分析：React.ReactNode；
    }) {
      const showAnalytics = true； // 可以基于用户权限、功能标志等。
    
      返回（
        <div>
          <主>{子}</主>
          {showAnalytics && <aside>{analytics}</aside>}
        </div>
      ）；
    }

**注意：** 此模式适用于任何布局级别（根或功能范围）。

## 拦截路由

拦截路由允许您在当前布局中加载路由，同时保留当前页面的上下文。

### 拦截路由约定

* `(.)` \- 匹配同一级别的段
  * `(..)` \- 匹配上一级的段
  * `(..)(..)` \- 匹配上面两层的段
  * `(...)` \- 从根开始匹配段

### 具有拦截路由的模态模式
    
    
    应用程序/
    ├── 照片/
    │ ├── [id]/
    │ │ └── page.tsx # 完整照片页面
    │ └── page.tsx # 照片库
    ├── @modal/
    │ └── (.)照片/
    │ └── [id]/
    │ └── page.tsx # 模态照片视图
    └── 布局.tsx

### 模态模式的布局
    
    
    // 应用程序/layout.tsx
    导出默认函数Layout({
      孩子们，
      模态,
    }：{
      孩子：React.ReactNode；
      模态：React.ReactNode；
    }) {
      返回（
        <div>
          {孩子}
          {模态}
        </div>
      ）；
    }

### 模态组件
    
    
    // 应用程序/@modal/(.)photos/[id]/page.tsx
    从'@/components/Modal'导入模态；
    从 '@/components/PhotoView' 导入 PhotoView；
    
    导出默认异步函数 PhotoModal({
      参数，
    }：{
      参数: { id: 字符串 };
    }) {
      const photo =等待 getPhoto(params.id);
    
      返回（
        <模态>
          <PhotoView 照片={照片} />
        </模态>
      ）；
    }
    
    // 应用程序/@modal/default.tsx
    导出默认函数 Default() {
      返回空值；
    }

### 客户端模态组件
    
    
    // 组件/Modal.tsx
    '使用客户端'；
    
    从 'next/navigation' 导入 { useRouter }；
    从 'react' 导入 { useEffect, useRef };
    
    导出默认函数 Modal({ Children }: { Children: React.ReactNode }) {
      const 路由器 = useRouter();
      constdialogRef = useRef<HTMLDialogElement>(null);
    
      使用效果（（）=> {
        dialogRef.current?.showModal();
      }, []);
    
      常量handleClose = () => {
        路由器.back();
      };
    
      返回（
        <dialog ref={dialogRef} onClose={handleClose}>
          <button onClick={handleClose}>关闭</button>
          {孩子}
        </对话框>
      ）；
    }

## 误差边界

### 基本误差边界
    
    
    // 应用程序/error.tsx
    '使用客户端'；
    
    导出默认函数Error({
      错误，
      重置，
    }：{
      错误：错误&{摘要？：字符串}；
      重置：() => 无效；
    }) {
      返回（
        <div>
          <h2>出了点问题！</h2>
          <p>{错误消息}</p>
          <button onClick={reset}>重试</button>
        </div>
      ）；
    }

### 嵌套误差边界
    
    
    // 应用程序/仪表板/error.tsx
    '使用客户端'；
    
    导出默认函数 DashboardError({
      错误，
      重置，
    }：{
      错误：错误；
      重置：() => 无效；
    }) {
      返回（
        <div className="仪表板错误">
          <h2>仪表板错误</h2>
          <p>{错误消息}</p>
          <button onClick={reset}>重试</button>
        </div>
      ）；
    }

### 全局误差边界
    
    
    // 应用程序/全局错误.tsx
    '使用客户端'；
    
    导出默认函数 GlobalError({
      错误，
      重置，
    }：{
      错误：错误&{摘要？：字符串}；
      重置：() => 无效；
    }) {
      返回（
        <html>
          <正文>
            <h2>应用程序错误</h2>
            <p>{错误消息}</p>
            <button onClick={reset}>重试</button>
          </正文>
        </html>
      ）；
    }

### 未找到边界
    
    
    // 应用程序/not-found.tsx
    从“下一个/链接”导入链接；
    
    导出默认函数 NotFound() {
      返回（
        <div>
          <h2>找不到页面</h2>
          <p>找不到请求的资源</p>
          <Link href="/">返回首页</Link>
        </div>
      ）；
    }
    
    // 以编程方式触发
    从 'next/navigation' 导入 { notFound }；
    
    导出默认异步函数 Page({ params }: { params: { id: string } }) {
      const post =等待 getPost(params.id);
    
      如果（！post）{
        未找到（）；
      }
    
      返回<div>{post.title}</div>;
    }

## 草稿模式

草稿模式允许您从无头 CMS 预览草稿内容。

### 启用草稿模式
    
    
    // 应用程序/api/draft/route.ts
    从'next/headers'导入{draftMode}；
    从“下一步/导航”导入{重定向}；
    
    导出异步函数 GET(请求: 请求) {
      const { searchParams } = 新 URL(request.url);
      const Secret = searchParams.get('秘密');
      const slug = searchParams.get('slug');
    
      // 检查秘密
      if (秘密!== process.env.DRAFT_SECRET) {
        return Response.json({ message: '无效令牌' }, { status: 401 });
      }
    
      // 启用草稿模式
      const 草稿 = 等待草稿模式();
      草稿.enable();
    
      // 重定向到获取的帖子的路径
      重定向（slug || '/'）；
    }

### 禁用草稿模式
    
    
    // 应用程序/api/draft/disable/route.ts
    从'next/headers'导入{draftMode}；
    从“下一步/导航”导入{重定向}；
    
    导出异步函数 GET() {
      const 草稿 = 等待草稿模式();
      草稿.disable();
      重定向（'/'）；
    }

### 在页面中使用草稿模式
    
    
    // 应用程序/帖子/[slug]/page.tsx
    从'next/headers'导入{draftMode}；
    
    导出默认异步函数 Post({ params }: { params: { slug: string } }) {
      const 草稿 = 等待草稿模式();
      const isDraft = Draft.isEnabled;
    
      // 获取草稿或已发布的内容
      const post =等待 getPost(params.slug, isDraft);
    
      返回（
        <文章>
          {是草稿 && (
            <div className="草稿横幅">
              <p>草稿模式激活</p>
              <a href="/api/draft/disable">退出草稿模式</a>
            </div>
          )}
          <h1>{帖子.标题}</h1>
          <div>{post.content}</div>
        </文章>
      ）；
    }

## 直播和悬念

### 带有悬念的基本流媒体
    
    
    // 应用程序/仪表板/page.tsx
    从'react'导入{Suspense}；
    
    导出默认函数 Dashboard() {
      返回（
        <div>
          <h1>仪表板</h1>
    
          <Suspense Fallback={<StatsSkeleton />}>
            <统计数据/>
          </悬念>
    
          <Suspense Fallback={<RecentActivitySkeleton />}>
            <最近活动/>
          </悬念>
        </div>
      ）；
    }
    
    异步函数 Stats() {
      const stats = 等待 fetchStats(); // 慢查询
      返回 <div className="stats">{JSON.stringify(stats)}</div>;
    }
    
    异步函数RecentActivity() {
      const 活动 = 等待 fetchRecentActivity();
      返回（
        <ul>
          {activity.map((项目) => (
            <li key={item.id}>{item.description}</li>
          ))}
        </ul>
      ）；
    }

### 嵌套悬念边界
    
    
    // 应用程序/page.tsx
    从'react'导入{Suspense}；
    
    导出默认函数 Page() {
      返回（
        <div>
          <标题/>
    
          <Suspense Fallback={<PageSkeleton />}>
            <主要内容/>
          </悬念>
        </div>
      ）；
    }
    
    异步函数 MainContent() {
      const 数据 = 等待 fetchMainData();
    
      返回（
        <div>
          <h2>{数据.标题}</h2>
    
          <Suspense Fallback={<CommentsSkeleton />}>
            <评论postId={data.id} />
          </悬念>
        </div>
      ）；
    }
    
    异步函数 Comments({ postId }: { postId: string }) {
      const 评论 = 等待 fetchComments(postId);
      返回（
        <ul>
          {comments.map((c) => <li key={c.id}>{c.text}</li>)}
        </ul>
      ）；
    }

### 使用loading.tsx 加载状态
    
    
    // 应用程序/仪表板/loading.tsx
    导出默认函数 Loading() {
      返回（
        <div className="加载骨架">
          <div className="骨架头" />
          <div className="骨架体" />
        </div>
      ）；
    }

### 使用加载 UI 进行流式传输
    
    
    // 应用程序/帖子/loading.tsx
    导出默认函数 PostsLoading() {
      返回（
        <div>
          {[1, 2, 3].map((i) => (
            <div key={i} className="post-sculpture">
              <div className="骨架标题" />
              <div className="骨架摘录" />
            </div>
          ))}
        </div>
      ）；
    }

## 高级模式

### 通过服务器操作进行乐观更新
    
    
    // 应用程序/组件/LikeButton.tsx
    '使用客户端'；
    
    从 'react' 导入 { useOptimistic } ；
    从'@/app/actions'导入{likePost}；
    
    导出默认函数 LikeButton({
      帖子 ID,
      最初的喜欢，
    }：{
      帖子ID：字符串；
      初始点赞数：数量；
    }) {
      const [optimisticLikes, addOptimisticLike] = useOptimistic(
        最初的喜欢，
        （状态，金额：数字）=>状态+金额
      ）；
    
      const handleLike = async () => {
        添加乐观喜欢（1）；
        等待 likePost(postId);
      };
    
      返回（
        <按钮onClick={handleLike}>
          喜欢：{optimisticLikes}
        </按钮>
      ）；
    }

### 使用表单进行渐进式增强
    
    
    // 应用程序/帖子/新/page.tsx
    '使用客户端'；
    
    从 'react-dom' 导入 { useFormState, useFormStatus };
    从'@/app/actions'导入{createPost}；
    
    函数提交按钮() {
      const { 待处理 } = useFormStatus();
    
      返回（
        <按钮类型=“提交”禁用= {待处理}>
          {待定？ '创建...' : '创建帖子'}
        </按钮>
      ）；
    }
    
    导出默认函数 NewPost() {
      const [state, formAction] = useFormState(createPost, null);
    
      返回（
        <表单操作={formAction}>
          <input name="title" placeholder="标题" 必需 />
          <textarea name =“内容”占位符=“内容”必需/>
    
          {状态？.错误&&(
            <div className="错误">
              {Object.entries(state.errors).map(([字段，消息]) => (
                <div key={字段}>
                  {messages.map((msg) => <p key={msg}>{msg}</p>)}
                </div>
              ))}
            </div>
          )}
    
          <提交按钮/>
        </形式>
      ）；
    }

## 总结

* **路由处理程序** \- 带有 HTTP 方法导出的 `route.ts` 文件中的 API 端点
  * **服务器操作** \- 使用“use server”指令进行服务器端突变
  * **并行路由** \- 使用“@folder”语法同时呈现多个页面
  * **拦截路由** \- 使用模态的 `(.)` 语法在上下文中加载路由
  * **错误边界** \- 使用 `error.tsx` 和 `global-error.tsx` 处理错误
  * **草稿模式** \- 从 CMS 预览草稿内容
  * **流式传输** \- 具有悬念边界的渐进式渲染
  * **Cookies** \- 在路由处理程序和服务器操作中访问和设置 cookie
  * **重新验证** \- 使用 `revalidatePath` 和 `revalidateTag` 使缓存无效</article></body></html>

Nextjs 高级路由

包含技能