SuperAPI AI 工具集

nextjs-server-side-error-debugging

编程与开发

查看项目

更新于 10-16 06:38

技能介绍

用途

该技能用于调试 Next.js 中的服务端错误,主要针对 getServerSideProps、getStaticProps 以及 API 路由。服务端错误不会出现在浏览器控制台中,因此当你在错误的地方查找时,调试会变得困难:浏览器只显示通用错误页面或 500 状态,而 DevTools 中没有堆栈跟踪或有用信息。

触发条件

该技能适用于以下情况:

  • 页面显示 "Internal Server Error" 或自定义错误页
  • 浏览器控制台没有错误,或只有通用的 fetch 失败
  • 正在使用 getServerSideProps、getStaticProps 或 API 路由
  • 错误仅在页面刷新或直接导航时出现(而非客户端跳转)
  • 错误是间歇性的,难以在浏览器中复现

常见的误导性症状:

  • "Unhandled Runtime Error" 弹窗未显示真正原因
  • Network 标签显示 500,但响应体为空或为通用内容
  • 添加 console.log 后错误消失(时序问题)

使用方式

第 1 步:检查终端

带有完整堆栈跟踪的实际错误会出现在运行 npm run dev 或 next dev 的终端中。这是首先要查看的地方。

# 如果看不到终端,查找进程
ps aux | grep next
# 或重启并显示输出
npm run dev

第 2 步:添加显式错误处理

为持续调试,可用 try-catch 包裹服务端代码:

export async function getServerSideProps(context) {
  try {
    const data = await fetchSomething();
    return { props: { data } };
  } catch (error) {
    console.error('getServerSideProps error:', error);
    // 返回错误状态而不是抛出
    return { props: { error: error.message } };
  }
}

第 3 步:处理生产环境错误

检查托管提供商的日志:

  • Vercel:Dashboard → Project → Logs(Functions 标签)
  • AWS:CloudWatch Logs
  • Netlify:Dashboard 中的 Functions 标签
  • 自托管:检查 Node.js 进程日志

第 4 步:常见原因

  • 环境变量:生产环境缺失但本地存在
  • 数据库连接:连接字符串问题、冷启动
  • 导入错误:仅服务端代码被意外导入到客户端
  • Async/await:异步操作缺少 await
  • JSON 序列化:无法序列化的对象(日期、函数)

验证

检查终端后,你应该能看到:

  • 带文件名和行号的完整堆栈跟踪
  • 实际错误消息(而非通用 500)
  • 若添加了 console.log 语句,可看到变量值

示例

症状:用户报告点击链接后页面显示 "Internal Server Error"。

排查:

  1. 打开浏览器 DevTools → Console:为空
  2. Network 标签显示:GET /dashboard → 500
  3. 检查运行 npm run dev 的终端:
Error: Cannot read property 'id' of undefined
    at getServerSideProps (/app/pages/dashboard.tsx:15:25)
    at renderToHTML (/app/node_modules/next/dist/server/render.js:428:22)

找到原因:数据库查询返回 null 而非用户对象。

限制与注意事项

  • 在开发环境中,Next.js 有时会显示错误覆盖层,但其细节通常少于终端输出
  • next.config.js 中的 reactStrictMode: true 会导致服务端函数在开发环境中双重执行,可能使调试变得混乱
  • 对于 API 路由,错误会出现在与页面错误相同的终端中
  • 客户端错误(useEffect、事件处理器中)确实会出现在浏览器控制台——该技能仅适用于服务端代码
  • 如果使用 next start(本地生产模式),错误可能不够详细;检查 NODE_ENV 并考虑添加自定义错误日志