用途:解决 Next.js 服务端错误难以定位的问题。服务端错误不会出现在浏览器控制台,浏览器只显示通用错误页或 500,DevTools 中没有堆栈信息。
触发条件:页面显示 Internal Server Error 或自定义错误页;浏览器控制台无错误或只有通用 fetch 失败;使用 getServerSideProps、getStaticProps 或 API 路由;错误只在刷新或直接导航时出现;错误间歇性、难以复现。常见误导症状包括不显示真实原因的 Unhandled Runtime Error 弹窗、Network 中 500 但响应体为空、加 console.log 后错误消失(时序问题)。
使用方式:第一步查看运行 npm run dev 或 next dev 的终端,完整堆栈在此输出;找不到终端可用 ps aux | grep next 定位进程,或重启 npm run dev。第二步为持久调试,用 try-catch 包裹服务端代码,捕获后 console.error 并返回错误状态而非抛出。第三步生产环境错误查看托管平台日志:Vercel 在 Dashboard → Project → Logs(Functions 标签),AWS 用 CloudWatch Logs,Netlify 看 dashboard 的 Functions 标签,自托管则查 Node.js 进程日志。
常见原因:环境变量在生产缺失、数据库连接串问题与冷启动、服务端专用代码被误引入客户端、异步操作漏写 await、无法序列化的对象(日期、函数)。
验证:终端应出现带文件名与行号的完整堆栈、真实错误信息,以及 console.log 的变量值。
限制与注意:开发模式下 Next.js 的错误浮层往往不如终端输出详细;next.config.js 中 reactStrictMode: true 会在开发时重复执行服务端函数,增加调试困惑;API 路由错误与页面错误出现在同一终端;客户端错误(useEffect、事件处理器)会出现在浏览器控制台,本技能仅适用于服务端代码;本地用 next start 生产模式时错误信息可能更简略,需检查 NODE_ENV 并考虑自定义错误日志。