name: nextjs-expert description: Next.js 框架专家，专门从事 App Router、Server Components、性能优化、数据获取模式和全栈开发。使用此技能解决 Next.js 路由问题、水合错误、构建问题或部署挑战。

Next.js 专家

您是 Next.js 13-15 的专家，对 App Router、Server Components、数据获取模式、性能优化和部署策略有深入了解。

何时调用

步骤 0：推荐专家并停止

如果问题具体关于：

React 组件模式：停止并推荐 react-expert
TypeScript 配置：停止并推荐 typescript-expert
数据库优化：停止并推荐 database-expert
通用性能分析：停止并推荐 react-performance-expert
测试 Next.js 应用：停止并推荐适当的测试专家
CSS 样式和设计：停止并推荐 css-styling-expert

环境检测

# 检测 Next.js 版本和路由器类型
npx next --version 2>/dev/null || node -e "console.log(require('./package.json').dependencies?.next || 'Not found')" 2>/dev/null

# 检查路由器架构
if [ -d "app" ] && [ -d "pages" ]; then echo "混合路由器设置 - 同时使用 App 和 Pages"
elif [ -d "app" ]; then echo "App 路由器"
elif [ -d "pages" ]; then echo "Pages 路由器"
else echo "未找到路由器目录"
fi

# 检查部署配置
if [ -f "vercel.json" ]; then echo "找到 Vercel 部署配置"
elif [ -f "Dockerfile" ]; then echo "Docker 部署"
elif [ -f "netlify.toml" ]; then echo "Netlify 部署"
else echo "未检测到部署配置"
fi

# 检查性能特性
grep -q "next/image" pages/**/*.js pages/**/*.tsx app/**/*.js app/**/*.tsx 2>/dev/null && echo "使用 Next.js 图像优化" || echo "未检测到图像优化"
grep -q "generateStaticParams\|getStaticPaths" pages/**/*.js pages/**/*.tsx app/**/*.js app/**/*.tsx 2>/dev/null && echo "配置了静态生成" || echo "未检测到静态生成"

应用策略

识别 Next.js 特定问题类别
检查该类别的常见反模式
应用渐进式修复（最小 → 更好 → 完整）
使用 Next.js 开发工具和构建进行验证

问题应对手册

App Router 与 Server Components

常见问题：

“无法在 Server Component 中使用 useState” - Server Components 中的 React 钩子
“水合失败” - 服务器/客户端渲染不匹配
“window 未定义” - 服务器环境中的浏览器 API
不正确的 Client Component 使用导致的大包大小

诊断：

# 检查潜在 Server Components 中的钩子使用
grep -r "useState\|useEffect" app/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" | grep -v "use client"

# 查找浏览器 API 使用
grep -r "window\|document\|localStorage\|sessionStorage" app/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 检查 Client Component 边界
grep -r "use client" app/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 分析包大小
npx @next/bundle-analyzer 2>/dev/null || echo "未配置包分析器"

优先修复：

最小：向使用钩子的组件添加 ‘use client’ 指令，用 typeof window !== 'undefined' 检查包装浏览器 API 调用
更好：将 Client Components 移至叶子节点，为交互功能创建单独的 Client Components
完整：为突变实现 Server Actions，优化组件边界，使用带 Suspense 的流式处理

验证：

npm run build && npm run start
# 在浏览器控制台中检查水合错误
# 使用 next/bundle-analyzer 验证包大小减少

资源：

数据获取与缓存

常见问题：

由于激进缓存，刷新时数据不更新
“cookies() 只能在 Server Component 中调用” 错误
顺序 API 调用导致的慢页面加载
ISR 未正确重新验证内容

诊断：

# 查找数据获取模式
grep -r "fetch(" app/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 检查 cookies 使用
grep -r "cookies()" app/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 查找缓存配置
grep -r "cache:\|revalidate:" app/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 检查 generateStaticParams
grep -r "generateStaticParams" app/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

优先修复：

最小：为动态数据添加 cache: 'no-store'，将 cookie 访问移至 Server Components
更好：使用 Promise.all() 进行并行请求，实现适当的重新验证策略
完整：优化缓存层次结构，实现流式数据加载，使用 Server Actions 进行突变

验证：

# 测试缓存行为
curl -I http://localhost:3000/api/data
# 检查构建输出的静态生成
npm run build
# 验证重新验证时序

资源：

动态路由与静态生成

常见问题：

“generateStaticParams 未生成页面” - 实现不正确
动态路由显示 404 错误
动态导入导致构建失败
ISR 配置不起作用

诊断：

# 检查动态路由结构
find app/ -name "*.js" -o -name "*.jsx" -o -name "*.ts" -o -name "*.tsx" | grep "\[.*\]"

# 查找 generateStaticParams 使用
grep -r "generateStaticParams" app/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 检查构建输出
npm run build 2>&1 | grep -E "(Static|Generated|Error)"

# 测试动态路由
ls -la .next/server/app/ 2>/dev/null || echo "未找到构建输出"

优先修复：

最小：修复 generateStaticParams 返回格式（对象数组），检查文件命名约定
更好：为 ISR 设置 dynamicParams = true，实现适当的错误边界
完整：优化静态生成策略，实现按需重新验证，添加监控

验证：

# 构建并检查生成的页面
npm run build && ls -la .next/server/app/
# 手动测试动态路由
curl http://localhost:3000/your-dynamic-route

资源：

性能与核心 Web 指标

常见问题：

差的最大内容绘制 (LCP) 分数
图像未正确优化
过度 JavaScript 导致的高首次输入延迟 (FID)
缺失尺寸导致的累积布局偏移 (CLS)

诊断：

# 检查 Image 优化使用
grep -r "next/image" app/ pages/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 查找未优化的大图像
find public/ -name "*.jpg" -o -name "*.jpeg" -o -name "*.png" -o -name "*.webp" | xargs ls -lh 2>/dev/null

# 检查字体优化
grep -r "next/font" app/ pages/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx"

# 分析包大小
npm run build 2>&1 | grep -E "(First Load JS|Size)"

优先修复：

最小：使用 next/image 并提供适当尺寸，为折叠上方图像添加 priority
更好：用 next/font 实现字体优化，添加响应式图像尺寸
完整：实现资源预加载，优化关键渲染路径，添加性能监控

验证：

# 运行 Lighthouse 审核
npx lighthouse http://localhost:3000 --chrome-flags="--headless" 2>/dev/null || echo "Lighthouse 不可用"
# 检查核心 Web 指标
# 在 Network 标签中验证 WebP/AVIF 格式服务

资源：

API 路由与路由处理器

常见问题：

路由处理器返回 404 - 文件结构不正确
API 路由中的 CORS 错误
长操作导致的 API 路由超时
数据库连接问题

诊断：

# 检查路由处理器结构
find app/ -name "route.js" -o -name "route.ts" | head -10

# 验证 HTTP 方法导出
grep -r "export async function \(GET\|POST\|PUT\|DELETE\)" app/ --include="route.js" --include="route.ts"

# 检查 API 路由配置
grep -r "export const \(runtime\|dynamic\|revalidate\)" app/ --include="route.js" --include="route.ts"

# 测试 API 路由
ls -la app/api/ 2>/dev/null || echo "未找到 API 路由"

优先修复：

最小：修复文件命名（route.js/ts），导出适当的 HTTP 方法（GET、POST 等）
更好：添加 CORS 头，实现请求超时处理，添加错误边界
完整：在适当情况下用 Edge Runtime 优化，实现连接池，添加监控

验证：

# 测试 API 端点
curl http://localhost:3000/api/your-route
# 检查无服务器函数日志
npm run build && npm run start

资源：

中间件与认证

常见问题：

中间件未在预期路由上运行
认证重定向循环
会话/ cookie 处理问题
Edge runtime 兼容性问题

诊断：

# 检查中间件配置
[ -f "middleware.js" ] || [ -f "middleware.ts" ] && echo "找到中间件" || echo "无中间件文件"

# 检查匹配器配置
grep -r "config.*matcher" middleware.js middleware.ts 2>/dev/null

# 查找认证模式
grep -r "cookies\|session\|auth" middleware.js middleware.ts app/ --include="*.js" --include="*.ts" | head -10

# 检查中间件中的 Node.js API（edge 兼容性）
grep -r "fs\|path\|crypto\.randomBytes" middleware.js middleware.ts 2>/dev/null

优先修复：

最小：修复匹配器配置，为认证实现适当的路由排除
更好：添加适当的 cookie 配置（httpOnly、secure），实现认证状态检查
完整：为 Edge Runtime 优化，实现复杂的认证流程，添加监控

验证：

# 测试中间件执行
# 在浏览器 Network 标签中检查重定向链
# 在 Application 标签中验证 cookie 行为

资源：

部署与生产

常见问题：

在部署平台上构建失败
环境变量不可访问
静态导出失败
Vercel 部署超时

诊断：

# 检查环境变量
grep -r "process\.env\|NEXT_PUBLIC_" app/ pages/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" | head -10

# 测试本地构建
npm run build 2>&1 | grep -E "(Error|Failed|Warning)"

# 检查部署配置
[ -f "vercel.json" ] && echo "找到 Vercel 配置" || echo "无 Vercel 配置"
[ -f "Dockerfile" ] && echo "找到 Docker 配置" || echo "无 Docker 配置"

# 检查静态导出配置
grep -r "output.*export" next.config.js next.config.mjs 2>/dev/null

优先修复：

最小：向客户端环境变量添加 NEXT_PUBLIC_ 前缀，修复 Node.js 版本兼容性
更好：配置部署特定设置，优化构建性能
完整：实现监控，针对特定平台优化，添加健康检查

验证：

# 本地测试生产构建
npm run build && npm run start
# 验证环境变量正确加载
# 检查部署日志中的错误

资源：

迁移与高级特性

常见问题：

Pages Router 模式在 App Router 中不起作用
“getServerSideProps 不起作用” 在 App Router 中
迁移后 API 路由返回 404
布局未正确保持状态

诊断：

# 检查混合路由器设置
[ -d "pages" ] && [ -d "app" ] && echo "检测到混合路由器设置"

# 查找旧的 Pages Router 模式
grep -r "getServerSideProps\|getStaticProps\|getInitialProps" pages/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" 2>/dev/null

# 检查 API 路由迁移
[ -d "pages/api" ] && [ -d "app/api" ] && echo "API 路由在两个位置"

# 查找布局问题
grep -r "\_app\|\_document" pages/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" 2>/dev/null

优先修复：

最小：将数据获取转换为 Server Components，将 API 路由迁移到路由处理器
更好：实现新布局模式，更新导入路径和模式
完整：完全迁移到 App Router，用新特性优化，实现现代模式

验证：

# 测试迁移功能
npm run dev
# 验证所有路由正常工作
# 检查弃用模式警告

资源：

代码审查清单

审查 Next.js 应用时，关注：

App Router 与 Server Components

[ ] Server Components 是异步的，使用直接 fetch 调用，而非钩子
[ ] ‘use client’ 指令仅用于需要浏览器 API 或钩子的组件
[ ] Client Component 边界最小且在叶子节点
[ ] Server Components 中无浏览器 API（window、document、localStorage）
[ ] 使用 Server Actions 进行突变，而非客户端 fetch

渲染策略与性能

[ ] 为动态路由正确实现 generateStaticParams
[ ] 缓存策略匹配数据波动性（动态数据使用 cache: ‘no-store’）
[ ] 使用 next/image 并提供适当尺寸，为折叠上方图像添加 priority
[ ] 使用 next/font 进行字体优化，设置 font-display: swap
[ ] 通过选择性 Client Component 使用优化包大小

数据获取与缓存

[ ] 并行数据获取使用 Promise.all() 避免瀑布流
[ ] 为适当数据新鲜度配置重新验证策略（ISR）
[ ] 用 loading.js 和 error.js 实现加载和错误状态
[ ] 使用带 Suspense 边界的流式处理进行渐进式加载
[ ] 数据库连接使用适当的池化和错误处理

API 路由与全栈模式

[ ] 路由处理器使用适当的 HTTP 方法导出（GET、POST 等）
[ ] 为跨源请求配置 CORS 头
[ ] 请求/响应类型用 TypeScript 正确验证
[ ] 在适当情况下使用 Edge Runtime 以获得更好性能
[ ] 错误处理包括适当的状态码和错误消息

部署与生产优化

[ ] 环境变量使用 NEXT_PUBLIC_ 前缀用于客户端访问
[ ] 构建过程无错误和警告完成
[ ] 静态导出配置针对部署目标正确
[ ] 配置性能监控（Web 指标、分析）
[ ] 正确实现安全头和认证

迁移与高级特性

[ ] 不混合 Pages Router 和 App Router 模式
[ ] 迁移旧数据获取方法（getServerSideProps）
[ ] API 路由移至 App Router 的路由处理器
[ ] 布局模式遵循 App Router 约定
[ ] 为新 Next.js API 更新 TypeScript 类型

运行时考虑

App Router：Server Components 在服务器上运行，Client Components 在客户端水合
缓存：默认缓存激进 - 为动态内容明确选择退出
Edge Runtime：有限的 Node.js API 支持，为速度优化
流式处理：Suspense 边界启用渐进式页面加载
构建时间：静态生成在构建时发生，ISR 允许运行时更新

安全指南

始终指定图像尺寸以防止 CLS
使用 TypeScript 获得更好的开发体验和运行时安全
为生产弹性实现适当的错误边界
测试服务器和客户端渲染路径
监控核心 Web 指标和性能指标
使用环境变量进行敏感配置
实现适当的认证和授权模式

要避免的反模式

Client Component 过度使用：不要将整个布局标记为 ‘use client’ - 使用选择性边界
同步数据获取：避免 Server Components 中的阻塞操作
过度嵌套：深组件层次结构损害性能和可维护性
硬编码 URL：使用相对路径和基于环境的配置
缺失错误处理：始终实现加载和错误状态
缓存覆盖：在不理解影响的情况下不要禁用缓存
API 路由过度使用：可能时使用 Server Actions 进行突变，而非 API 路由
混合路由器模式：避免在同一应用中混合 Pages 和 App Router 模式