NextJS开发服务器频繁随机断开连接问题求助

问题背景 #

开发Next.js 13.4.19项目时，代码更新后偶尔出现开发服务器随机断开，报错核心为TypeError: fetch failed，底层是connect ECONNREFUSED 127.0.0.1:xxxx（随机端口），完整报错如下：

TypeError: fetch failed
    at Object.fetch (D:\vsc\msaf-next\node_modules\next\dist\compiled\undici\index.js:1:26669)
    at runMicrotasks (<anonymous>)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
    at async invokeRequest (D:\vsc\msaf-next\node_modules\next\dist\server\lib\server-ipc\invoke-request.js:17:12)
    at async invokeRender (D:\vsc\msaf-next\node_modules\next\dist\server\lib\router-server.js:254:29)
    at async handleRequest (D:\vsc\msaf-next\node_modules\next\dist\server\lib\router-server.js:447:24)
    at async requestHandler (D:\vsc\msaf-next\node_modules\next\dist\server\lib\router-server.js:464:13)
    at async Server.<anonymous> (D:\vsc\msaf-next\node_modules\next\dist\server\lib\start-server.js:117:13) {
  cause: Error: connect ECONNREFUSED 127.0.0.1:53023
      at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1247:16) {
    errno: -4078,
    code: 'ECONNREFUSED',
    syscall: 'connect',
    address: '127.0.0.1',
    port: 53023
  }
}

核心原因分析 #

这个错误本质是Next.js开发服务器内部的IPC（进程间通信）调用失败，通常是热更新时子进程未正确启动/回收，或者undici（Next.js内置的fetch实现）与Node.js版本、项目配置存在兼容性冲突。

解决方案 #

• 升级Next.js版本
  13.4.19存在已知的开发服务器IPC稳定性问题，升级到13.4.20或更高稳定版（如13.5.x、14.x）可直接修复该问题：

  npm install next@latest
  # 或 yarn add next@latest
  

• 清理项目缓存与依赖
  缓存损坏或依赖冲突可能导致进程异常，执行以下操作重置：

  # 删除缓存与依赖目录
  rm -rf .next node_modules
  # 清除包管理器缓存
  npm cache clean --force
  # 重新安装依赖
  npm install
  

• 固定开发服务器端口
  随机端口可能触发系统端口回收问题，指定固定端口启动：

  next dev -p 3000
  

  也可在next.config.js中永久配置：

  module.exports = {
    serverPort: 3000,
  }
  

• 调整Fast Refresh配置
  部分场景下Fast Refresh的热更新逻辑与IPC冲突，可尝试临时禁用排查：

  module.exports = {
    fastRefresh: false,
  }
  

  若禁用后问题解决，优先通过升级Next.js版本替代完全禁用。

• 检查Node.js版本
  确保使用Next.js官方推荐的Node.js版本（18.x或20.x LTS），旧版本Node.js与undici存在兼容性问题，可通过nvm切换：

  nvm use 18
  

• 排查自定义代码
  若项目使用了自定义服务器（server.js）或中间件，检查是否存在：

  • 未正确处理的异步逻辑导致进程未退出
  • 端口占用或监听逻辑错误
  • 中间件中未设置超时的fetch请求

内容的提问来源于stack exchange，提问作者salm00n