commit c7776c6cfc591867e4c73df355991a7254cd026f
Author: wehub-skill-sync <skill-sync@wehub.local>
Date:   Mon Jul 13 21:35:53 2026 +0800

    chore: import zh skill nextjs-advanced-routing

diff --git a/README.wehub.md b/README.wehub.md
new file mode 100644
index 0000000..be2e649
--- /dev/null
+++ b/README.wehub.md
@@ -0,0 +1,9 @@
+# WeHub 来源说明
+
+- Skill 名称：`nextjs-advanced-routing`
+- 中文类目：Next.js App Router 前端界面与架构实现
+- 上游仓库：`wsimmonds__claude-nextjs-skills`
+- 上游路径：`nextjs-advanced-routing/SKILL.md`
+- 上游链接：https://github.com/wsimmonds/claude-nextjs-skills/blob/HEAD/nextjs-advanced-routing/SKILL.md
+- 本仓库为 WeHub 中文 Skill 汉化包，基于 skill 市场筛选 Top200 清单整理
+- 原作者、版权和许可证信息以上游仓库为准
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..4bddbc1
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,1478 @@
+---
+name: nextjs-advanced-routing
+description: 高级 Next.js App Router 模式指南，涵盖路由处理器、并行路由、拦截路由、服务端操作、错误边界、草稿模式以及基于 Suspense 的流式渲染。**关键内容**：服务端操作（action.ts、actions.ts 文件、'use server' 指令）、从客户端组件设置 Cookie 以及表单处理。适用于涉及服务端操作、表单提交、Cookie、数据变更、API 路由、`route.ts`、并行路由、拦截路由或流式渲染的场景。对于将服务端操作与客户端组件分离至关重要。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Next.js 高级路由
+
+## 概述
+
+提供 Next.js App Router 高级特性的全面指南，包括路由处理器（API 路由）、并行路由、拦截路由、服务端操作、错误处理、草稿模式以及基于 Suspense 的流式渲染。
+
+## TypeScript：严禁使用 `any` 类型
+
+**关键规则：** 本代码库已启用 `@typescript-eslint/no-explicit-any`。使用 `any` 将导致构建失败。
+
+**❌ 错误用法：**
+```typescript
+function handleSubmit(e: any) { ... }
+const data: any[] = [];
+```
+
+**✅ 正确用法：**
+```typescript
+function handleSubmit(e: React.FormEvent<HTMLFormElement>) { ... }
+const data: string[] = [];
+```
+
+### 常见 Next.js 类型模式
+
+```typescript
+// 页面属性
+function Page({ params }: { params: { slug: string } }) { ... }
+function Page({ searchParams }: { searchParams: { [key: string]: string | string[] | undefined } }) { ... }
+
+// 表单事件
+const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => { ... }
+const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => { ... }
+
+// 服务端操作
+async function myAction(formData: FormData) { ... }
+```
+
+## 何时使用本技能
+
+在以下场景使用本技能：
+- 使用路由处理器创建 API 端点
+- 实现并行或拦截路由
+- 使用服务端操作构建表单
+- 设置 Cookie 或处理数据变更
+- 创建错误边界
+- 实现 CMS 预览的草稿模式
+- 设置流式渲染和 Suspense 边界
+- 构建复杂路由模式（模态框、抽屉）
+
+## ⚠️ 关键：服务端操作文件的命名与位置
+
+当需求中指定了特定文件名时，请严格遵循该指示。如果未指定名称，请选择最符合项目约定的选项——`app/actions.ts` 是多个操作集合的安全默认选择，而 `app/action.ts` 适用于单个表单处理器。
+
+### 在 `action.ts` 与 `actions.ts` 之间选择
+
+- **匹配现有模式：** 检查项目中是否已存在操作文件，若合适则扩展它。
+- **单个导出 vs 多个导出：** 单个操作优先使用 `action.ts`，一组相关操作优先使用 `actions.ts`。
+- **明确要求：** 如果需求方指定了具体名称，请不要更改。
+
+**位置指南**
+- 服务端操作应放在 `app/` 目录下，以便它们能参与 App Router 树。
+- 将文件放在调用它的 UI 旁边，除非它在多个路由之间共享。
+- 除非操作是从多个不同路由触发且保持仅为服务端工具，否则避免将其放在 `lib/` 或 `utils/` 中。
+
+**示例放置方式**
+```
+app/
+├── actions.ts       ← 支持多个路由的共享操作
+└── dashboard/
+    └── action.ts    ← 与单个页面共置的路由特定操作
+```
+
+### 示例：创建 action.ts
+
+```typescript
+// app/action.ts（单个操作示例）
+'use server';
+
+export async function submitForm(formData: FormData) {
+  const name = formData.get('name') as string;
+  // 处理表单
+  console.log('Submitted:', name);
+}
+```
+
+### 示例：创建 actions.ts
+
+```typescript
+// app/actions.ts（多个相关操作）
+'use server';
+
+export async function createPost(formData: FormData) {
+  // ...
+}
+
+export async function deletePost(id: string) {
+  // ...
+}
+```
+
+**请记住：** 当项目需求中明确写出了精确文件名时，请严格按此执行。
+
+## ⚠️ 关键：服务端操作返回类型——表单操作必须返回 void
+
+**这是 TypeScript 的要求，不可省略。即使你看到有代码从表单操作中返回数据，那段代码也是错误的。**
+
+当使用表单操作属性时：`<form action={serverAction}>`
+- 该函数**不能有 return 语句**（隐式返回 void）
+- TypeScript 会**拒绝任何返回值**，即使是 `return undefined` 或 `return null`
+- **重要提示：** 如果你在代码库中看到从表单操作返回数据的示例代码，请忽略它——这是一种反模式。通过删除 return 语句来修复它。
+
+❌ 错误用法（导致构建错误）：
+```typescript
+export async function saveForm(formData: FormData) {
+  'use server';
+
+  const name = formData.get('name') as string;
+  if (!name) throw new Error('Name required');
+
+  await db.save(name);
+  return { success: true }; // ❌ 构建错误：类型不匹配
+}
+
+// 在组件中：
+<form action={saveForm}>  {/* ❌ 期望一个 void 函数 */}
+  <input name="name" />
+</form>
+```
+
+✅ 正确做法——选项 1（简单表单操作，无返回值）：
+```typescript
+export async function saveForm(formData: FormData) {
+  'use server';
+
+  const name = formData.get('name') as string;
+
+  // 验证——抛出错误而非返回它们
+  if (!name) throw new Error('Name required');
+
+  await db.save(name);
+  revalidatePath('/'); // 触发 UI 更新
+  // 无 return 语句——隐式返回 void
+}
+
+// 在组件中：
+<form action={saveForm}>
+  <input name="name" required />
+  <button type="submit">Save</button>
+</form>
+```
+
+✅ 正确做法——选项 2（配合 useActionState 获取反馈）：
+```typescript
+export async function saveForm(prevState: any, formData: FormData) {
+  'use server';
+
+  const name = formData.get('name') as string;
+  if (!name) return { error: 'Name required' };
+
+  await db.save(name);
+  return { success: true, message: 'Saved!' }; // ✅ 配合 useActionState 可用
+}
+
+// 在组件中：
+'use client';
+const [state, action] = useActionState(saveForm, null);
+
+return (
+  <form action={action}>
+    <input name="name" required />
+    <button type="submit">Save</button>
+    {state?.error && <p>{state.error}</p>}
+    {state?.success && <p>{state.message}</p>}
+  </form>
+);
+```
+
+**关键规则：** `<form action={...}>` 期望返回 `void`。如果需要返回数据，请使用 `useActionState`。
+
+## 路由处理器（API 路由）
+
+### 基本路由处理器
+
+路由处理器替代了 Pages Router 中的 API 路由。在 `route.ts` 或 `route.js` 文件中创建它们。
+
+```typescript
+// app/api/hello/route.ts
+export async function GET(request: Request) {
+  return Response.json({ message: 'Hello World' });
+}
+
+export async function POST(request: Request) {
+  const body = await request.json();
+
+  return Response.json({
+    message: 'Data received',
+    data: body
+  });
+}
+```
+
+### 支持的 HTTP 方法
+
+```typescript
+// app/api/items/route.ts
+export async function GET(request: Request) { }
+export async function POST(request: Request) { }
+export async function PUT(request: Request) { }
+export async function PATCH(request: Request) { }
+export async function DELETE(request: Request) { }
+export async function HEAD(request: Request) { }
+export async function OPTIONS(request: Request) { }
+```
+
+### 动态路由处理器
+
+```typescript
+// app/api/posts/[id]/route.ts
+export async function GET(
+  request: Request,
+  { params }: { params: { id: string } }
+) {
+  const id = params.id;
+  const post = await db.posts.findUnique({ where: { id } });
+
+  return Response.json(post);
+}
+
+export async function DELETE(
+  request: Request,
+  { params }: { params: { id: string } }
+) {
+  await db.posts.delete({ where: { id: params.id } });
+
+  return Response.json({ success: true });
+}
+```
+
+### 请求头部与 Cookie
+
+```typescript
+// app/api/profile/route.ts
+import { cookies, headers } from 'next/headers';
+
+export async function GET(request: Request) {
+  // 访问请求头部
+  const headersList = await headers();
+  const authorization = headersList.get('authorization');
+
+  // 访问 Cookie
+  const cookieStore = await cookies();
+  const sessionToken = cookieStore.get('session-token');
+
+  if (!sessionToken) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const user = await fetchUser(sessionToken.value);
+
+  return Response.json(user);
+}
+```
+
+### 在路由处理器中设置 Cookie
+
+```typescript
+// app/api/login/route.ts
+import { cookies } from 'next/headers';
+
+export async function POST(request: Request) {
+  const { email, password } = await request.json();
+
+  const token = await authenticate(email, password);
+
+  if (!token) {
+    return Response.json({ error: 'Invalid credentials' }, { status: 401 });
+  }
+
+  // 设置 Cookie
+  const cookieStore = await cookies();
+  cookieStore.set('session-token', token, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: 60 * 60 * 24 * 7, // 1 周
+    path: '/',
+  });
+
+  return Response.json({ success: true });
+}
+```
+
+### CORS 配置
+
+```typescript
+// app/api/public/route.ts
+export async function GET(request: Request) {
+  const data = await fetchData();
+
+  return Response.json(data, {
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    },
+  });
+}
+
+export async function OPTIONS(request: Request) {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    },
+  });
+}
+```
+
+### 流式响应
+
+```typescript
+// app/api/stream/route.ts
+export async function GET() {
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream({
+    async start(controller) {
+      for (let i = 0; i < 10; i++) {
+        controller.enqueue(encoder.encode(`data: ${i}\n\n`));
+        await new Promise(resolve => setTimeout(resolve, 1000));
+      }
+      controller.close();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+    },
+  });
+}
+```
+
+## 服务端操作
+
+服务端操作允许在不创建 API 端点的情况下执行服务端数据变更。
+
+### 基本服务端操作（无返回值）
+
+```typescript
+// app/actions.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+  const content = formData.get('content') as string;
+
+  const post = await db.posts.create({
+    data: { title, content },
+  });
+
+  revalidatePath('/posts');
+  // 无 return 语句——带有表单的服务端操作应返回 void
+}
+```
+
+**注意：** 有关返回数据与不返回数据的模式对比，请参见下面的"在表单中使用服务端操作"章节。
+
+### ⚠️ 关键：服务端操作文件组织
+
+**文件命名精确性：**
+- 当需求方指定了文件名（例如"在一个名为 `action.ts` 的文件中创建一个服务端操作"），请严格按此执行。
+- 常见文件名：`action.ts`（单数）或 `actions.ts`（复数）——选择与需求说明或现有代码匹配的那一个。
+- 将文件放在适当的目录中：通常是 `app/action.ts` 或 `app/actions.ts`。
+
+**'use server' 指令的两种模式：**
+
+**模式 1：文件级（推荐用于多个操作）：**
+```typescript
+// app/actions.ts
+'use server';  // 在文件顶部——所有导出都是服务端操作
+
+export async function createPost(formData: FormData) { ... }
+export async function updatePost(formData: FormData) { ... }
+export async function deletePost(postId: string) { ... }
+```
+
+**模式 2：函数级（适用于单个操作或混合文件）：**
+```typescript
+// app/action.ts 或任何文件
+export async function createPost(formData: FormData) {
+  'use server';  // 在函数内部——只有此函数是服务端操作
+
+  const title = formData.get('title') as string;
+  await db.posts.create({ data: { title } });
+}
+```
+
+**客户端组件调用服务端操作：**
+
+当客户端组件需要调用服务端操作时（例如 onClick、表单提交）：
+1. 在单独的文件中创建带有 'use server' 指令的服务端操作
+2. 在客户端组件中导入并使用它
+
+**✅ 正确模式：**
+```typescript
+// app/actions.ts - 服务端操作文件
+'use server';
+
+import { cookies } from 'next/headers';
+
+export async function updateUserPreference(key: string, value: string) {
+  const cookieStore = await cookies();
+  cookieStore.set(key, value);
+
+  // 或执行其他服务端操作
+  await db.userSettings.update({ [key]: value });
+}
+
+// app/InteractiveButton.tsx - 客户端组件
+'use client';
+
+import { updateUserPreference } from './actions';
+
+export default function InteractiveButton() {
+  const handleClick = () => {
+    updateUserPreference('theme', 'dark');
+  };
+
+  return (
+    <button onClick={handleClick}>
+      Update Preference
+    </button>
+  );
+}
+```
+
+**❌ 错误用法——在同一个文件中混用 'use server' 和 'use client'：**
+```typescript
+// app/CookieButton.tsx
+'use client';  // 此文件是客户端组件
+
+export async function setCookie() {
+  'use server';  // 错误！不能在客户端组件文件中包含服务端操作
+  // ...
+}
+```
+
+### 在表单中使用服务端操作——两种模式
+
+#### 模式 1：简单表单操作（返回 void / 抛出错误）
+
+**关键：** 当直接使用表单 `action` 属性时，服务端操作**必须返回 void**（无返回值）。不要返回 `{ success: true }` 或任何对象。
+
+**验证规则：** 检查所有输入，如果验证失败则抛出错误。不要返回错误对象。
+
+⚠️ **重要提示：** 即使你在代码库中看到从表单操作返回 `{ success: true }` 的示例代码，也**不要复制该模式**。那段代码是反模式。始终：
+1. 检查/验证输入
+2. 如果验证失败则抛出错误（不要返回错误对象）
+3. 处理请求
+4. 不返回任何内容（返回 void）
+
+表单操作的正确模式：
+
+```typescript
+// app/actions.ts
+'use server';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+  const content = formData.get('content') as string;
+
+  // 验证
+  if (!title || !content) {
+    throw new Error('Title and content are required');
+  }
+
+  // 保存到数据库
+  await db.posts.create({ data: { title, content } });
+
+  // 重新验证或重定向——无需返回
+  revalidatePath('/posts');
+}
+
+// app/posts/new/page.tsx
+import { createPost } from '@/app/actions';
+
+export default function NewPost() {
+  return (
+    <form action={createPost}>
+      <input name="title" placeholder="Title" required />
+      <textarea name="content" placeholder="Content" required />
+      <button type="submit">Create Post</button>
+    </form>
+  );
+}
+```
+
+#### 模式 2：配合 useActionState 的表单（返回数据）
+
+当你需要显示成功/错误消息时，使用 `useActionState`：
+
+```typescript
+// app/actions.ts
+'use server';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+  const content = formData.get('content') as string;
+
+  if (!title || !content) {
+    return { success: false, error: 'Title and content required' };
+  }
+
+  const post = await db.posts.create({ data: { title, content } });
+  return { success: true, post };
+}
+
+// app/posts/new/page.tsx
+'use client';
+
+import { createPost } from '@/app/actions';
+import { useActionState } from 'react';
+
+export default function NewPost() {
+  const [state, action, isPending] = useActionState(createPost, null);
+
+  return (
+    <form action={action}>
+      <input name="title" placeholder="Title" required />
+      <textarea name="content" placeholder="Content" required />
+      <button type="submit" disabled={isPending}>
+        {isPending ? 'Creating...' : 'Create Post'}
+      </button>
+      {state?.error && <p style={{ color: 'red' }}>{state.error}</p>}
+      {state?.success && <p style={{ color: 'green' }}>Post created!</p>}
+    </form>
+  );
+}
+```
+
+**关键区别：**
+- **模式 1：** 仅表单操作，服务端操作返回 void，使用 `revalidatePath`
+- **模式 2：** 配合 `useActionState`，服务端操作返回数据用于展示
+
+### 表单验证示例——多个字段
+
+当验证多个必填字段时，应一起检查它们，如果有任何缺失则抛出错误：
+
+```typescript
+'use server';
+
+export async function 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 (!name || !email || !message) {
+    throw new Error('All fields are required');
+  }
+
+  // 保存到数据库
+  console.log('Saving contact message:', { name, email, message });
+
+  // 无 return——隐式返回 void
+}
+```
+
+这将：
+1. ✅ 通过 TypeScript 检查（返回 void）
+2. ✅ 在处理之前验证所有输入
+3. ✅ 如果验证失败则抛出错误（阻止数据库保存）
+4. ✅ 不返回错误对象（否则会破坏表单操作的类型检查）
+
+### 客户端组件中的服务端操作
+
+```typescript
+// app/actions.ts
+'use server';
+
+export async function updateUsername(userId: string, username: string) {
+  await db.users.update({
+    where: { id: userId },
+    data: { username },
+  });
+
+  return { success: true };
+}
+
+// app/components/UsernameForm.tsx
+'use client';
+
+import { updateUsername } from '@/app/actions';
+import { useState } from 'react';
+
+export default function UsernameForm({ userId }: { userId: string }) {
+  const [username, setUsername] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+
+    await updateUsername(userId, username);
+
+    setLoading(false);
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        value={username}
+        onChange={(e) => setUsername(e.target.value)}
+        placeholder="New username"
+      />
+      <button type="submit" disabled={loading}>
+        {loading ? 'Updating...' : 'Update'}
+      </button>
+    </form>
+  );
+}
+```
+
+### 带验证的服务端操作（抛出错误）
+
+当直接使用表单操作时，验证失败应抛出错误（不要返回错误对象）：
+
+```typescript
+// app/actions.ts
+'use server';
+
+import { revalidatePath } from 'next/cache';
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string;
+  const content = formData.get('content') as string;
+
+  // 验证——如果无效则抛出错误
+  if (!title || !content) {
+    throw new Error('Title and content are required');
+  }
+
+  if (title.length > 100) {
+    throw new Error('Title must be less than 100 characters');
+  }
+
+  if (content.length < 10) {
+    throw new Error('Content must be at least 10 characters');
+  }
+
+  // 保存到数据库
+  const post = await db.posts.create({
+    data: { title, content },
+  });
+
+  revalidatePath('/posts');
+  // 无 return——表单操作返回 void
+}
+```
+
+**如需返回验证状态：** 如果你需要返回验证错误或在 UI 中显示它们，请改用 `useActionState`（上述模式 2）。
+
+### 在服务端操作中设置 Cookie
+
+```typescript
+// app/actions.ts
+'use server';
+
+import { cookies } from 'next/headers';
+
+export async function setTheme(theme: 'light' | 'dark') {
+  const cookieStore = await cookies();
+
+  cookieStore.set('theme', theme, {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    maxAge: 60 * 60 * 24 * 365, // 1 年
+    path: '/',
+  });
+
+  return { success: true };
+}
+```
+
+### 重新验证与重定向
+
+```typescript
+// app/actions.ts
+'use server';
+
+import { revalidatePath, revalidateTag } from 'next/cache';
+import { redirect } from 'next/navigation';
+
+export async function deletePost(postId: string) {
+  await db.posts.delete({ where: { id: postId } });
+
+  // 重新验证特定路径
+  revalidatePath('/posts');
+
+  // 或按缓存标签重新验证
+  revalidateTag('posts');
+
+  // 删除后重定向
+  redirect('/posts');
+}
+```
+
+## 第 0 步：确定并行路由的作用域
+
+在实现并行路由之前，先确定它们应该放在路由结构中的哪个位置。
+
+### 分析路由上下文
+
+**关键问题：** 此功能是针对特定页面/区域，还是针对整个应用？
+
+- **特定页面/区域** → 在该路由目录下创建
+- **整个应用** → 在根级别创建
+
+### 路由作用域决策过程
+
+**当需求中提到特定功能或页面时：**
+```
+"为 [功能名称] 创建包含 X 和 Y 的并行路由"
+→ 结构：app/[功能名称]/@x/ 和 app/[功能名称]/@y/
+```
+
+**当需求涵盖应用级布局时：**
+```
+"创建一个包含 X 和 Y 并行路由的应用"
+→ 结构：app/@x/ 和 app/@y/
+```
+
+### 常见作用域错误
+
+❌ **错误——并行路由位于错误的作用域：**
+```
+请求："为 [特定功能] 创建包含 X 和 Y 区域的页面"
+
+app/
+├── @x/              # ❌ 在根级别创建——影响整个应用！
+├── @y/              # ❌ 错误的作用域
+└── layout.tsx       # ❌ 不必要地修改了根布局
+```
+
+这会使并行路由变为全局，而它们本应是功能特定的。
+
+✅ **正确——并行路由适当限定作用域：**
+```
+请求："为 [特定功能] 创建包含 X 和 Y 区域的页面"
+
+app/
+├── [特定功能]/
+│   ├── @x/          # ✅ 限定在此功能内
+│   ├── @y/          # ✅ 仅影响此路由
+│   └── layout.tsx   # ✅ 功能特定的布局
+└── layout.tsx       # 根布局不变
+```
+
+### 决策标准
+
+1. **分析需求**——寻找特定功能/页面名称
+   - 提到了特定名词/功能？→ 在 `app/[该功能]/` 下创建
+   - 一般的应用级描述？→ 确定是根级别还是新建路由
+
+2. **考虑 URL 结构**——该功能应位于哪个 URL？
+   - `/feature` 路径 → 使用 `app/feature/@slots/`
+   - 根路径 `/` → 使用 `app/@slots/`
+   - 嵌套路径 `/parent/feature` → 使用 `app/parent/feature/@slots/`
+
+3. **考虑作用域影响**——会影响应用的多少部分？
+   - 仅影响一个功能/页面？→ 限定到功能目录
+   - 影响多个相关页面？→ 限定到父目录
+   - 影响整个应用？→ 使用根级别
+
+### 实际示例
+
+**示例 1：功能特定的并行路由**
+```
+场景：用户个人资料页面需要帖子和活动的标签页
+
+分析：
+- "用户个人资料页面" = 特定功能
+- 应位于 /profile URL
+- 仅影响个人资料页面
+
+结构：
+app/
+├── profile/
+│   ├── @posts/
+│   │   └── page.tsx
+│   ├── @activity/
+│   │   └── page.tsx
+│   └── layout.tsx        # 接收 posts、activity 插槽
+```
+
+**示例 2：应用级并行路由**
+```
+场景：整体应用布局需要暴露侧边栏和主内容插槽
+
+分析：
+- "应用布局" = 根级别
+- 影响整个应用
+- 应位于根级别
+
+结构：
+app/
+├── @sidebar/
+│   └── page.tsx
+├── @main/
+│   └── page.tsx
+└── layout.tsx            # 带插槽的根布局
+```
+
+**示例 3：嵌套区域并行路由**
+```
+场景：管理区域添加了一个带图表和表格的分析视图
+
+分析：
+- "管理面板" = 现有区域
+- "分析视图" = 子区域
+- 应位于 /admin/analytics URL
+
+结构：
+app/
+├── admin/
+│   ├── analytics/
+│   │   ├── @charts/
+│   │   │   └── page.tsx
+│   │   ├── @tables/
+│   │   │   └── page.tsx
+│   │   └── layout.tsx    # 分析特定的布局
+│   └── layout.tsx        # 管理布局（不变）
+```
+
+### 快速参考
+
+| 需求模式 | 路由作用域 | 示例结构 |
+|---------------|-------------|-------------------|
+| 功能特定的需求 | `app/[功能]/` | `app/profile/@tab/` |
+| 父区域下的子区域 | `app/[父级]/[区域]/` | `app/admin/analytics/@view/` |
+| 应用级布局需求 | `app/` | `app/@sidebar/` |
+| 带多个面板的页面 | `app/[页面]/` | `app/settings/@panel/` |
+
+**关键规则：** 在默认使用根级并行路由之前，务必先分析需求中的作用域指示符。
+
+## 并行路由
+
+并行路由允许在同一布局中同时渲染多个页面。
+
+### ⚠️ 重要提示：首先理解路由作用域
+
+在创建并行路由之前，请先**查阅上面的"第 0 步：确定并行路由的作用域"**以确定正确的目录层级。
+
+不要默认在根级别创建并行路由——根据需求中提到的功能/页面适当地限定作用域。
+
+### 创建并行路由（功能限定作用域）
+
+适用于功能特定的并行路由（最常见的情况）：
+
+```
+app/
+├── [功能名称]/
+│   ├── @slot1/
+│   │   └── page.tsx
+│   ├── @slot2/
+│   │   └── page.tsx
+│   ├── layout.tsx       # 接受插槽属性的功能布局
+│   └── page.tsx         # 功能主页面
+```
+
+### 创建并行路由（根级别）
+
+适用于应用级并行路由（较少见）：
+
+```
+app/
+├── @slot1/
+│   └── page.tsx
+├── @slot2/
+│   └── page.tsx
+├── layout.tsx           # 带插槽的根布局
+└── page.tsx
+```
+
+### 带并行路由的布局（功能限定作用域示例）
+
+适用于具有并行路由的功能：
+
+```typescript
+// app/[功能]/layout.tsx
+export default function FeatureLayout({
+  children,
+  slot1,
+  slot2,
+}: {
+  children: React.ReactNode;
+  slot1: React.ReactNode;
+  slot2: React.ReactNode;
+}) {
+  return (
+    <div>
+      <h1>Feature Page</h1>
+      <div className="main">{children}</div>
+      <div className="slots">
+        <div className="slot1">{slot1}</div>
+        <div className="slot2">{slot2}</div>
+      </div>
+    </div>
+  );
+}
+```
+
+### 带并行路由的布局（根级别示例）
+
+适用于应用级并行路由：
+
+```typescript
+// app/layout.tsx
+export default function RootLayout({
+  children,
+  sidebar,
+  main,
+}: {
+  children: React.ReactNode;
+  sidebar: React.ReactNode;
+  main: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <div className="app-layout">
+          <aside>{sidebar}</aside>
+          <main>{main}</main>
+          {children}
+        </div>
+      </body>
+    </html>
+  );
+}
+```
+
+### 默认并行路由
+
+创建 `default.tsx` 来处理未匹配的路由或提供备用 UI：
+
+```typescript
+// 功能限定作用域：app/[功能]/@slot1/default.tsx
+export default function Default() {
+  return null; // 或默认 UI
+}
+
+// 根级别：app/@sidebar/default.tsx
+export default function Default() {
+  return <div>Default sidebar content</div>;
+}
+```
+
+### 条件并行路由
+
+并行路由可以根据运行时条件有条件地渲染：
+
+```typescript
+// app/[功能]/layout.tsx（或任何包含并行路由的布局）
+export default function Layout({
+  children,
+  analytics,
+}: {
+  children: React.ReactNode;
+  analytics: React.ReactNode;
+}) {
+  const showAnalytics = true; // 可基于用户权限、功能开关等设置
+
+  return (
+    <div>
+      <main>{children}</main>
+      {showAnalytics && <aside>{analytics}</aside>}
+    </div>
+  );
+}
+```
+
+**注意：** 此模式适用于任何布局层级（根级别或功能限定作用域）。
+
+## 拦截路由
+
+拦截路由允许你在当前布局中加载一个路由，同时保持当前页面的上下文。
+
+### 拦截路由约定
+
+- `(.)` - 匹配同一层级的路径段
+- `(..)` - 匹配上一层的路径段
+- `(..)(..)` - 匹配上两层的路径段
+- `(...)` - 从根目录匹配路径段
+
+### 带拦截路由的模态框模式
+
+```
+app/
+├── photos/
+│   ├── [id]/
+│   │   └── page.tsx        # 完整照片页面
+│   └── page.tsx            # 照片画廊
+├── @modal/
+│   └── (.)photos/
+│       └── [id]/
+│           └── page.tsx    # 模态框照片视图
+└── layout.tsx
+```
+
+### 模态框模式的布局
+
+```typescript
+// app/layout.tsx
+export default function Layout({
+  children,
+  modal,
+}: {
+  children: React.ReactNode;
+  modal: React.ReactNode;
+}) {
+  return (
+    <div>
+      {children}
+      {modal}
+    </div>
+  );
+}
+```
+
+### 模态框组件
+
+```typescript
+// app/@modal/(.)photos/[id]/page.tsx
+import Modal from '@/components/Modal';
+import PhotoView from '@/components/PhotoView';
+
+export default async function PhotoModal({
+  params,
+}: {
+  params: { id: string };
+}) {
+  const photo = await getPhoto(params.id);
+
+  return (
+    <Modal>
+      <PhotoView photo={photo} />
+    </Modal>
+  );
+}
+
+// app/@modal/default.tsx
+export default function Default() {
+  return null;
+}
+```
+
+### 客户端模态框组件
+
+```typescript
+// components/Modal.tsx
+'use client';
+
+import { useRouter } from 'next/navigation';
+import { useEffect, useRef } from 'react';
+
+export default function Modal({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  useEffect(() => {
+    dialogRef.current?.showModal();
+  }, []);
+
+  const handleClose = () => {
+    router.back();
+  };
+
+  return (
+    <dialog ref={dialogRef} onClose={handleClose}>
+      <button onClick={handleClose}>Close</button>
+      {children}
+    </dialog>
+  );
+}
+```
+
+## 错误边界
+
+### 基本错误边界
+
+```typescript
+// app/error.tsx
+'use client';
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <div>
+      <h2>Something went wrong!</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+### 嵌套错误边界
+
+```typescript
+// app/dashboard/error.tsx
+'use client';
+
+export default function DashboardError({
+  error,
+  reset,
+}: {
+  error: Error;
+  reset: () => void;
+}) {
+  return (
+    <div className="dashboard-error">
+      <h2>Dashboard Error</h2>
+      <p>{error.message}</p>
+      <button onClick={reset}>Retry</button>
+    </div>
+  );
+}
+```
+
+### 全局错误边界
+
+```typescript
+// app/global-error.tsx
+'use client';
+
+export default function GlobalError({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  return (
+    <html>
+      <body>
+        <h2>Application Error</h2>
+        <p>{error.message}</p>
+        <button onClick={reset}>Try again</button>
+      </body>
+    </html>
+  );
+}
+```
+
+### 未找到页面边界
+
+```typescript
+// app/not-found.tsx
+import Link from 'next/link';
+
+export default function NotFound() {
+  return (
+    <div>
+      <h2>Page Not Found</h2>
+      <p>Could not find requested resource</p>
+      <Link href="/">Return Home</Link>
+    </div>
+  );
+}
+
+// 程序化触发
+import { notFound } from 'next/navigation';
+
+export default async function Page({ params }: { params: { id: string } }) {
+  const post = await getPost(params.id);
+
+  if (!post) {
+    notFound();
+  }
+
+  return <div>{post.title}</div>;
+}
+```
+
+## 草稿模式
+
+草稿模式允许你预览来自无头 CMS 的草稿内容。
+
+### 启用草稿模式
+
+```typescript
+// app/api/draft/route.ts
+import { draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url);
+  const secret = searchParams.get('secret');
+  const slug = searchParams.get('slug');
+
+  // 检查密钥
+  if (secret !== process.env.DRAFT_SECRET) {
+    return Response.json({ message: 'Invalid token' }, { status: 401 });
+  }
+
+  // 启用草稿模式
+  const draft = await draftMode();
+  draft.enable();
+
+  // 重定向到获取到的文章路径
+  redirect(slug || '/');
+}
+```
+
+### 禁用草稿模式
+
+```typescript
+// app/api/draft/disable/route.ts
+import { draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+export async function GET() {
+  const draft = await draftMode();
+  draft.disable();
+  redirect('/');
+}
+```
+
+### 在页面中使用草稿模式
+
+```typescript
+// app/posts/[slug]/page.tsx
+import { draftMode } from 'next/headers';
+
+export default async function Post({ params }: { params: { slug: string } }) {
+  const draft = await draftMode();
+  const isDraft = draft.isEnabled;
+
+  // 获取草稿或已发布内容
+  const post = await getPost(params.slug, isDraft);
+
+  return (
+    <article>
+      {isDraft && (
+        <div className="draft-banner">
+          <p>Draft Mode Active</p>
+          <a href="/api/draft/disable">Exit Draft Mode</a>
+        </div>
+      )}
+      <h1>{post.title}</h1>
+      <div>{post.content}</div>
+    </article>
+  );
+}
+```
+
+## 流式渲染与 Suspense
+
+### 使用 Suspense 的基本流式渲染
+
+```typescript
+// app/dashboard/page.tsx
+import { Suspense } from 'react';
+
+export default function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      <Suspense fallback={<StatsSkeleton />}>
+        <Stats />
+      </Suspense>
+
+      <Suspense fallback={<RecentActivitySkeleton />}>
+        <RecentActivity />
+      </Suspense>
+    </div>
+  );
+}
+
+async function Stats() {
+  const stats = await fetchStats(); // 慢查询
+  return <div className="stats">{JSON.stringify(stats)}</div>;
+}
+
+async function RecentActivity() {
+  const activity = await fetchRecentActivity();
+  return (
+    <ul>
+      {activity.map((item) => (
+        <li key={item.id}>{item.description}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### 嵌套 Suspense 边界
+
+```typescript
+// app/page.tsx
+import { Suspense } from 'react';
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+
+      <Suspense fallback={<PageSkeleton />}>
+        <MainContent />
+      </Suspense>
+    </div>
+  );
+}
+
+async function MainContent() {
+  const data = await fetchMainData();
+
+  return (
+    <div>
+      <h2>{data.title}</h2>
+
+      <Suspense fallback={<CommentsSkeleton />}>
+        <Comments postId={data.id} />
+      </Suspense>
+    </div>
+  );
+}
+
+async function Comments({ postId }: { postId: string }) {
+  const comments = await fetchComments(postId);
+  return (
+    <ul>
+      {comments.map((c) => <li key={c.id}>{c.text}</li>)}
+    </ul>
+  );
+}
+```
+
+### 使用 loading.tsx 的加载状态
+
+```typescript
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return (
+    <div className="loading-skeleton">
+      <div className="skeleton-header" />
+      <div className="skeleton-body" />
+    </div>
+  );
+}
+```
+
+### 使用加载 UI 的流式渲染
+
+```typescript
+// app/posts/loading.tsx
+export default function PostsLoading() {
+  return (
+    <div>
+      {[1, 2, 3].map((i) => (
+        <div key={i} className="post-skeleton">
+          <div className="skeleton-title" />
+          <div className="skeleton-excerpt" />
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## 高级模式
+
+### 带服务端操作的乐观更新
+
+```typescript
+// app/components/LikeButton.tsx
+'use client';
+
+import { useOptimistic } from 'react';
+import { likePost } from '@/app/actions';
+
+export default function LikeButton({
+  postId,
+  initialLikes,
+}: {
+  postId: string;
+  initialLikes: number;
+}) {
+  const [optimisticLikes, addOptimisticLike] = useOptimistic(
+    initialLikes,
+    (state, amount: number) => state + amount
+  );
+
+  const handleLike = async () => {
+    addOptimisticLike(1);
+    await likePost(postId);
+  };
+
+  return (
+    <button onClick={handleLike}>
+      Likes: {optimisticLikes}
+    </button>
+  );
+}
+```
+
+### 渐进式增强表单
+
+```typescript
+// app/posts/new/page.tsx
+'use client';
+
+import { useFormState, useFormStatus } from 'react-dom';
+import { createPost } from '@/app/actions';
+
+function SubmitButton() {
+  const { pending } = useFormStatus();
+
+  return (
+    <button type="submit" disabled={pending}>
+      {pending ? 'Creating...' : 'Create Post'}
+    </button>
+  );
+}
+
+export default function NewPost() {
+  const [state, formAction] = useFormState(createPost, null);
+
+  return (
+    <form action={formAction}>
+      <input name="title" placeholder="Title" required />
+      <textarea name="content" placeholder="Content" required />
+
+      {state?.errors && (
+        <div className="errors">
+          {Object.entries(state.errors).map(([field, messages]) => (
+            <div key={field}>
+              {messages.map((msg) => <p key={msg}>{msg}</p>)}
+            </div>
+          ))}
+        </div>
+      )}
+
+      <SubmitButton />
+    </form>
+  );
+}
+```
+
+## 总结
+
+- **路由处理器** - 在 `route.ts` 文件中使用 HTTP 方法导出的 API 端点
+- **服务端操作** - 使用 'use server' 指令的服务端数据变更
+- **并行路由** - 使用 `@folder` 语法同时渲染多个页面
+- **拦截路由** - 使用 `(.)` 语法在上下文中加载路由，用于模态框
+- **错误边界** - 使用 `error.tsx` 和 `global-error.tsx` 处理错误
+- **草稿模式** - 预览来自 CMS 的草稿内容
+- **流式渲染** - 使用 Suspense 边界进行渐进式渲染
+- **Cookie** - 在路由处理器和服务端操作中访问和设置 Cookie
+- **重新验证** - 使用 `revalidatePath` 和 `revalidateTag` 使缓存失效