用途:在编写或审查 Next.js 16+ 代码时应用一套最佳实践规则,目标环境为 Next.js 16+、App Router、Node.js 20.9+、TypeScript 5+。
主要能力: Next.js 16 模式:proxy.ts 取代 middleware.ts,运行于 Node.js 运行时,使用 export function proxy(request: NextRequest) 与 export const config = { matcher },redirect、rewrite、headers、cookies 等 API 保持一致;迁移命令为 npx @next/codemod@canary middleware-to-proxy .。Turbopack 为默认打包器,可用 next build --webpack、next dev --webpack 退出。Cache Components 通过 cacheComponents: true 和 "use cache" 指令选择性启用,面向 PPR。异步 API 中 params、searchParams、cookies()、headers() 均为异步,需要 await。缓存方面 revalidateTag(tag, profile) 需要第二个参数,Server Actions 中用 updateTag() 实现读己之写,refresh() 处理未缓存数据。
文件约定:项目结构与特殊文件、路由段(动态、catch-all、分组)、并行与拦截路由、proxy.ts(v16 取代 middleware.ts,Node.js 运行时)。
RSC 边界:检测无效的 React Server Component 模式,包括异步客户端组件、不可序列化 props、Server Action 异常。
异步模式:异步 params 与 searchParams、异步 cookies() 与 headers()、迁移 codemod。
运行时机选择:默认 Node.js 运行时,以及 Edge 运行时的适用场景。
指令:'use client'、'use server'(React)与 'use cache'(Next.js)。
函数:导航 hooks(useRouter、usePathname、useSearchParams、useParams);服务端函数(cookies、headers、draftMode、after);生成函数(generateStaticParams、generateMetadata)。
错误处理:error.tsx、global-error.tsx、not-found.tsx;redirect、permanentRedirect、notFound;forbidden、unauthorized(鉴权错误);catch 块中的 unstable_rethrow。
数据模式:Server Components、Server Actions 与 Route Handlers 的选择;避免数据瀑布(Promise.all、Suspense、preload);客户端组件数据获取。
路由处理器:route.ts 基础;GET 处理器与 page.tsx 的冲突;无 React DOM 的环境行为;与 Server Actions 的选用对比。
元数据与 OG 图片:静态与动态 metadata、generateMetadata、使用 next/og 生成 OG 图片、基于文件的元数据约定。
图片优化:始终用 next/image 而非 <img>、远程图片配置、响应式 sizes 属性、模糊占位、LCP 的 priority 加载。
字体优化:next/font 配置、Google Fonts 与本地字体、Tailwind CSS 集成、预加载子集。
打包:不兼容服务端的包、CSS 引入(不用 link 标签)、已内置的 polyfill、ESM/CommonJS 问题、包体积分析。
脚本:next/script 与原生 script 标签、内联脚本需 id、加载策略、用 @next/third-parties 接入 Google Analytics。
水合错误:常见成因(浏览器 API、日期、无效 HTML)、用错误浮层调试、各成因的修复方法。
Suspense 边界:useSearchParams 与 usePathname 导致的 CSR bailout、哪些 hooks 需要 Suspense 边界。
并行与拦截路由:@slot 与 (.) 拦截器实现模态框、用 default.tsx 做回退、用 router.back() 正确关闭模态框。
自托管:Docker 用 output: 'standalone'、多实例 ISR 的 cache handlers、可用与需额外配置的项。
调试技巧:用于 AI 辅助调试的 MCP 端点、用 --debug-build-paths 重新构建特定路由。
限制:原始资料未提供具体安装方式、收费或许可信息,暂未提供。