Next.js 最佳实践
在编写或审查 Next.js 代码时应用这些规则。
文件约定
参见 file-conventions.md 以了解：
- 项目结构和特殊文件
- 路由段（动态、捕获所有、分组）
- 并行与拦截路由
- v16 中的中间件重命名（middleware → proxy）
RSC 边界
检测无效的 React 服务器组件模式。
参见 rsc-boundaries.md 以了解：
- 异步客户端组件检测（无效）
- 不可序列化 props 检测
- 服务器操作异常
异步模式
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.tsxredirect、permanentRedirect、notFoundforbidden、unauthorized（认证错误）- 用于 catch 块的
unstable_rethrow
数据模式
参见 data-patterns.md 以了解：
- 服务器组件 vs 服务器操作 vs 路由处理器
- 避免数据瀑布（
Promise.all、Suspense、预加载） - 客户端组件数据获取
路由处理器
参见 route-handlers.md 以了解：
route.ts基础- GET 处理器与
page.tsx的冲突 - 环境行为（无 React DOM）
- 何时使用 vs 服务器操作
元数据与 OG 图片
参见 metadata.md 以了解：
- 静态和动态元数据
generateMetadata函数- 使用
next/og生成 OG 图片 - 基于文件的元数据约定
图片优化
参见 image.md 以了解：
- 始终使用
next/image而非<img> - 远程图片配置
- 响应式
sizes属性 - 模糊占位符
- LCP 优先级加载
字体优化
参见 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时的 CSR 回退 - 哪些钩子需要 Suspense 边界
并行与拦截路由
参见 parallel-routes.md 以了解：
- 使用
@slot和(.)拦截器的模态框模式 - 用于回退的
default.tsx - 使用
router.back()正确关闭模态框
自托管
参见 self-hosting.md 以了解：
- Docker 的
output: 'standalone' - 多实例 ISR 的缓存处理器
- 哪些功能开箱即用，哪些需要额外配置
调试技巧
参见 debug-tricks.md 以了解：
- 用于 AI 辅助调试的 MCP 端点
- 使用
--debug-build-paths重建特定路由