用途
该技能用于调试 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"。
排查:
- 打开浏览器 DevTools → Console:为空
- Network 标签显示:GET /dashboard → 500
- 检查运行 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 并考虑添加自定义错误日志