Next.js 最佳实践

在编写或审查 Next.js 代码时应用这些规则。

文件约定

请参阅 file-conventions.md 了解：

• 项目结构和特殊文件
• 路由段（动态、全捕获、分组）
• 并行路由和拦截路由
• v16 中的中间件重命名（middleware → proxy）

RSC 边界

检测无效的 React 服务器组件模式。

请参阅 rsc-boundaries.md 了解：

• 异步客户端组件检测（无效）
• 不可序列化的属性检测
• 服务器操作异常

异步模式

Next.js 15+ 异步 API 变更。

请参阅 async-patterns.md 了解：

• 异步 params 和 searchParams
• 异步 cookies() 和 headers()
• 迁移 codemod

运行时选择

请参阅 runtime-selection.md 了解：

• 默认使用 Node.js 运行时
• 何时适合使用 Edge 运行时

指令

请参阅 directives.md 了解：

• 'use client', 'use server' (React)
• 'use cache' (Next.js)

函数

请参阅 functions.md 了解：

• 导航钩子：useRouter, usePathname, useSearchParams, useParams
• 服务器函数：cookies, headers, draftMode, after
• 生成函数：generateStaticParams, generateMetadata

错误处理

请参阅 error-handling.md 了解：

• error.tsx, global-error.tsx, not-found.tsx
• redirect, permanentRedirect, notFound
• forbidden, unauthorized（认证错误）
• unstable_rethrow 用于 catch 块

数据模式

请参阅 data-patterns.md 了解：

• 服务器组件 vs 服务器操作 vs 路由处理程序
• 避免数据瀑布（Promise.all, Suspense, preload）
• 客户端组件数据获取

路由处理程序

请参阅 route-handlers.md 了解：

• route.ts 基础知识
• GET 处理程序与 page.tsx 的冲突
• 环境行为（无 React DOM）
• 何时使用 vs 服务器操作

元数据与开放图谱图像

请参阅 metadata.md 了解：

• 静态和动态元数据
• generateMetadata 函数
• 使用 next/og 生成开放图谱图像
• 基于文件的元数据约定

图片优化

请参阅 image.md 了解：

• 始终使用 next/image 而非 <img>
• 远程图片配置
• 响应式 sizes 属性
• 模糊占位符
• 为最大内容绘制优先加载

字体优化

请参阅 font.md 了解：

• next/font 设置
• Google 字体、本地字体
• Tailwind CSS 集成
• 预加载字体子集

打包

请参阅 bundling.md 了解：

• 与服务器不兼容的包
• CSS 导入（非 link 标签）
• Polyfills（已包含）
• ESM/CommonJS 问题
• 包分析

脚本

请参阅 scripts.md 了解：

• next/script 与原生 script 标签
• 内联脚本需要 id
• 加载策略
• 使用 @next/third-parties 的 Google Analytics

水合错误

请参阅 hydration-error.md 了解：

• 常见原因（浏览器 API、日期、无效 HTML）
• 使用错误覆盖层调试
• 针对每种原因的修复方法

Suspense 边界

请参阅 suspense-boundaries.md 了解：

• 使用 useSearchParams 和 usePathname 导致的客户端渲染降级
• 哪些钩子需要 Suspense 边界

并行与拦截路由

请参阅 parallel-routes.md 了解：

• 使用 @slot 和 (.) 拦截器的模态框模式
• 用于回退的 default.tsx
• 使用 router.back() 正确关闭模态框

自托管

请参阅 self-hosting.md 了解：

• 用于 Docker 的 output: 'standalone'
• 用于多实例增量静态再生的缓存处理程序
• 哪些功能开箱即用，哪些需要额外设置

调试技巧

请参阅 debug-tricks.md 了解：

• 用于 AI 辅助调试的 MCP 端点
• 使用 --debug-build-paths 重新构建特定路由