next-best-practices

Next.js 最佳实践

编写或审查 Next.js 代码时，请遵循这些规则。

文件约定

参见 file-conventions.md，了解：

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

RSC 边界

检测无效的 React Server Component 模式。

参见 rsc-boundaries.md，了解：

• 异步客户端组件检测（无效）
• 不可序列化的 props 检测
• Server Action 例外情况

异步模式

Next.js 15+ 异步 API 变更。

参见 async-patterns.md，了解：

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

Runtime 选择

参见 runtime-selection.md，了解：

• 默认使用 Node.js runtime
• 适合使用 Edge runtime 的情况

指令

参见 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（身份验证错误）
• 用于 catch 块的 unstable_rethrow

数据模式

参见 data-patterns.md，了解：

• Server Components、Server Actions 和 Route Handlers 之间的区别
• 避免数据瀑布（Promise.all、Suspense、preload）
• 客户端组件数据获取

路由处理程序

参见 route-handlers.md，了解：

• route.ts 基础知识
• GET 处理程序与 page.tsx 冲突
• 环境行为（无 React DOM）
• 与 Server Actions 的适用场景对比

元数据和 OG 图片

参见 metadata.md，了解：

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

图片优化

参见 image.md，了解：

• 始终使用 next/image，而不是 <img>
• 远程图片配置
• 响应式 sizes 属性
• 模糊占位图
• LCP 优先加载

字体优化

参见 font.md，了解：

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

打包

参见 bundling.md，了解：

• 与服务端不兼容的包
• CSS 导入（而不是 link 标签）
• Polyfill（已包含）
• ESM/CommonJS 问题
• Bundle 分析

脚本

参见 scripts.md，了解：

• next/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 重新构建特定路由