如何调试Next.js开发服务器挂起无响应问题？怎样获取更多排查数据？

第一步：开启全量调试日志获取更详细的报错信息 #

启动开发服务时添加调试环境变量，输出Next.js和Node底层的运行日志：

• 输出Next.js全模块调试日志：DEBUG=next:* npm run dev（Windows环境可先执行set DEBUG=next:*再启动服务）
• 输出Node底层HTTP、网络连接日志：NODE_DEBUG=http,net npm run dev
• 打印GC垃圾回收日志，排查内存阻塞问题：NODE_OPTIONS="--trace-gc" npm run dev

第二步：检测活跃连接与服务运行状态 #

服务挂起时不需要直接杀进程，先执行以下操作采集状态：

• 查看3000端口（默认开发端口）的所有活跃连接：
  • Mac/Linux：lsof -i :3000
  • Windows：netstat -ano | findstr :3000
• 生成Node进程诊断报告：启动服务时添加参数NODE_OPTIONS="--report-uncaught-exception --report-on-signal"，服务挂起时执行kill -USR2 <进程ID>，会在当前目录生成JSON格式的诊断报告，包含所有活跃请求、句柄占用、堆内存统计信息。

第三步：常见根因快速排查 #

绝大多数开发服务挂起都可以通过以下方式定位：

• 排查循环重编译问题：检查是否有自动生成的文件（日志、临时缓存、构建产物）没有加入忽略列表，在next.config.js中配置watchOptions: { ignored: ['node_modules', '.next', './你的自动生成文件目录'] }，避免文件监听触发无限重编译。
• 排查异步阻塞问题：检查近期新增的页面、API路由中是否有未捕获异常的异步操作、无超时配置的请求、未释放的数据库/缓存连接，可先注释近期改动的代码，逐个缩小排查范围。
• 排查内存溢出问题：如果GC日志显示挂起前有频繁的Full GC，可调大Node堆内存上限：NODE_OPTIONS=--max-old-space-size=4096 npm run dev。
• 排查第三方依赖兼容问题：新建空白Next.js项目启动测试，如果空白项目不会挂起，可逐个迁移原项目的依赖、插件确认兼容问题。

第四步：开发服务性能分析方法 #

不需要手动解读CPU Profile和内存快照，用以下方式直接定位卡住的代码：

• 启动服务时添加--inspect参数：NODE_OPTIONS="--inspect" npm run dev
• 打开Chrome浏览器访问chrome://inspect，找到对应的Node进程点击 inspect 进入调试面板
• 服务挂起时点击调试面板的暂停按钮，调用栈会直接停在当前阻塞的代码位置，即可定位根因。

内容的提问来源于stack exchange，提问作者Yuji 'Tomita' Tomita