升级Next.js 12至13后出现ECONNREFUSED连接错误求助

问题现象 #

升级后启动应用（指定端口3002），终端出现随机端口的ECONNREFUSED错误，应用无法正常渲染，同时伴随Fast Refresh全量重载提示，且日志中存在next.config.js无效配置警告。

终端错误日志：

> dtpms-usrmgmt-ui@0.1.20 dev /run/media/rud31mp/drive2/Codes/typescript/dtpms/dtpms-usrmngr-ui
> next dev -p 3002

- ready started server on 0.0.0.0:3002, url: http://localhost:3002
- info Loaded env from /run/media/rud31mp/drive2/Codes/typescript/dtpms/dtpms-usrmngr-ui/.env.local
- warn Invalid next.config.js options detected: 
- warn     The root value has an unexpected property, externals, which is not in the list of allowed properties (amp, analyticsId, assetPrefix, basePath, cleanDistDir, compiler, compress, configOrigin, crossOrigin, devIndicators, distDir, env, eslint, excludeDefaultMomentLocales, experimental, exportPathMap, generateBuildId, generateEtags, headers, httpAgentOptions, i18n, images, modularizeImports, onDemandEntries, optimizeFonts, output, outputFileTracing, pageExtensions, poweredByHeader, productionBrowserSourceMaps, publicRuntimeConfig, reactStrictMode, redirects, rewrites, sassOptions, serverRuntimeConfig, skipMiddlewareUrlNormalize, skipTrailingSlashRedirect, staticPageGenerationTimeout, swcMinify, target, trailingSlash, transpilePackages, typescript, useFileSystemPublicRoutes, webpack).
- warn See more info here: https://nextjs.org/docs/messages/invalid-next-config
- event compiled client and server successfully in 1216 ms (311 modules)
- wait compiling...
- event compiled client and server successfully in 334 ms (311 modules)
- wait compiling /not-found (client and server)...
- event compiled client and server successfully in 694 ms (555 modules)
- warn Fast Refresh had to perform a full reload due to a runtime error.
- error Error: connect ECONNREFUSED 127.0.0.1:33241
    at TCPConnectWrap.afterConnect [as oncomplete] (node:net:1487:16)
    at TCPConnectWrap.callbackTrampoline (node:internal/async_hooks:130:17) {
  errno: -111,
  code: 'ECONNREFUSED',
  syscall: 'connect',
  address: '127.0.0.1',
  port: 33241
}
- wait compiling /_error (client and server)...
- event compiled client and server successfully in 385 ms (556 modules)

修复步骤 #

1. 修正next.config.js无效配置 #

日志明确指出根配置中的externals属性不被Next.js 13支持，需要将其迁移到webpack配置项内：

// 修正后的next.config.js示例
module.exports = {
  // 其他有效配置...
  webpack: (config, { isServer }) => {
    // 在这里添加你的externals配置
    config.externals = [...(config.externals || []), 'your-external-dependency'];
    return config;
  }
};

2. 清除项目缓存与重新安装依赖 #

升级后缓存文件可能存在版本冲突，执行以下操作：

• 删除.next构建目录：rm -rf .next
• 清除包管理器缓存：
  • npm: npm cache clean --force
  • yarn: yarn cache clean
  • pnpm: pnpm store prune
• 重新安装依赖：npm install（或对应包管理命令）

3. 排查Fast Refresh冲突 #

随机端口错误大概率与Fast Refresh的内部机制有关，可临时禁用排查：

// next.config.js中添加
module.exports = {
  experimental: {
    fastRefresh: false,
  }
};

如果禁用后问题消失，说明是Fast Refresh与某些依赖/配置不兼容，可尝试升级项目中的React、React-DOM版本至Next.js 13要求的最低版本（React 18+）。

4. 检查自定义端口与内部服务 #

• 确认没有其他脚本占用Next.js内部使用的随机端口范围
• 排查代码中是否存在自动生成随机端口并尝试连接的逻辑，比如自定义开发工具或代理配置

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