优先级:P0(关键)
实现指南
路由架构
- 结构:使用
app/ 目录。通过 app/dashboard/layout.tsx 定义路由,返回 {children};共享UI自动嵌套在 app/layout.tsx 中。使用 loading.tsx、error.tsx 和 not-found.tsx 处理状态。
- 段(Segments):使用 Route Groups(括号
(auth))组织功能,使其 从URL路径中排除。使用 动态路由(括号 [slug])并通过 generateStaticParams 定义静态路径。
- 高级路由:使用 并行路由(Parallel Routes)(
@modal),将插槽(slot)添加到父布局并提供 default.tsx 回退。使用 拦截路由(Intercepting Routes)((.)route)实现高级布局,如仪表板。
数据与函数
- Next.js 15+ 异步:始终
await params: Promise、searchParams、cookies() 和 headers()。
- 安全性:使用
middleware.ts 进行边缘端身份验证和重定向。确保所有 路由处理器(route.ts) 都经过适当的身份验证检查。
- RSC:默认使用 React Server Components(RSC)。仅在叶节点使用
'use client' 进行交互性操作(钩子/事件)。
- 错误边界:创建
app/dashboard/loading.tsx 以自动将路由包装在 Suspense边界 中。在 error.tsx 中,使用 'use client' 并提供一个 reset: () => void 函数。
代码片段
export default async function DashboardLayout({
children,
analytics,
}: {
children: React.ReactNode
analytics: React.ReactNode
}) {
const cookieStore = await cookies()
const theme = cookieStore.get('theme')
return (
<div className={theme?.value ?? 'light'}>
{children}
{analytics}
</div>
)
}
文件约定
- page.tsx:路由的UI。
- layout.tsx:包裹子元素的共享UI。在导航间保持持久化。
- loading.tsx:加载状态的Suspense边界。
- error.tsx:错误边界(必须是客户端组件)。
- route.ts:服务器端API端点。
结构模式
- 路由组(Route Groups):使用括号
(auth) 组织,不影响URL路径。
- 私有文件夹(Private Folders):使用下划线
_lib 排除在路由之外。
- 动态路由(Dynamic Routes):使用方括号
[slug] 或 [...slug](全捕获)。
最佳实践
- RSC边界:确保传递给客户端组件的props是可序列化的。参见 RSC边界与序列化。
- 并行路由(
@folder):在同一布局中渲染多个页面。使用 default.tsx 作为回退。
- 拦截路由(
(..)folder):在当前布局上下文中加载路由。
- 同地组织(Colocation):将组件文件、样式和测试存放在路由文件夹内。
- 布局(Layouts):使用根布局(
app/layout.tsx)放置 <html> 和 <body> 标签。
- 自托管标准
反模式
- 不要使用未等待的异步API:
params、cookies()、headers() 在Next.js 15+中是Promise;始终await。
- 不要在树根使用
'use client':将其放在叶子节点;保持布局和页面为服务器组件。
- 不要在嵌套布局中使用
<html>/<body>:只有 app/layout.tsx(根布局)应包含它们。
- 不要缺少
error.tsx:每个路由段都需要一个客户端组件错误边界。