Node.js 16升级17后localhost连接报ECONNREFUSED问题咨询

问题现象 #

Windows环境下不同Node.js版本的TCP客户端连接行为存在明确差异：

• Node.js 16.13.1环境下，以下TCP客户端代码可正常连接对应端口的运行中服务：

import net from 'net';

let socket = net.createConnection({
    host: 'localhost',
    port: 12345
})

• 升级到Node.js 17.7.2后，上述代码抛出ECONNREFUSED（连接被拒绝）错误，仅将host参数替换为'0.0.0.0'时可正常连接。
• 多轮复现验证确认：
  • 不传host参数使用官方文档标注的默认值localhost、显式传入host:'localhost'两种写法，在16版本可正常连接，17版本均报连接拒绝
  • 仅显式指定host:'0.0.0.0'的写法可在两个版本中都正常连通
  • 反复切换Node.js版本确认，该连接行为差异完全由Node.js版本决定，与业务代码无关，可稳定复现与规避
• 实际影响：现有代码中大量默认使用localhost作为连接主机名的逻辑全局替换成本高，用户自行输入的主机地址包含localhost时也会触发连接失败，需要额外添加地址转换逻辑，维护成本高。

根因验证测试 #

进一步测试确认，问题并非单纯由localhost域名解析错误导致，和Node.js 17版本的网络逻辑变更直接相关：

1. 测试环境搭建：启动3个Node.js TCP服务端，分别监听默认地址、显式绑定'0.0.0.0'、显式绑定'localhost'；使用3种不同host配置（默认、localhost、0.0.0.0）的客户端分别连接所有服务端，测试时客户端与服务端使用相同Node.js版本。
2. 测试结果：
   • Node.js 16.13.1环境下，所有客户端与服务端的组合均可正常连通
   • Node.js 17.7.2环境下，仅客户端配置的host与服务端监听地址完全匹配时才可连通，监听0.0.0.0的服务端无法被默认host、localhost配置的客户端连接
   • 非Node.js实现的、通过C++标准socket API绑定INADDR_ANY（即0.0.0.0）的服务，同样存在被Node.js 17的localhost客户端连接拒绝的问题

验证测试代码如下：

import net from 'net';

console.log(process.version);

const accepted = detail => socket => socket.write(detail, ()=>socket.end());

const serversReady = () => [ 
    new Promise(resolve => net.createServer(accepted('default')).listen(12345, function(){resolve(this)})),
    new Promise(resolve => net.createServer(accepted('localhost')).listen(12346, 'localhost', function(){resolve(this)})),
    new Promise(resolve => net.createServer(accepted('0.0.0.0')).listen(12347, '0.0.0.0', function(){resolve(this)}))
];

const ports = [[12345,'default'], [12346,'localhost'], [12347,'0.0.0.0']];
const hosts = [{}, {host:'localhost'}, {host:'0.0.0.0'}];

const clientsDone = () => ports.map(([port,whichserver]) => hosts.map(host => new Promise((resolve, reject) => {
    let opts = {...host, port:port};
    net.createConnection(opts)
        .on('error', e => (console.log(opts, 'to:'+whichserver, 'error', e.message), reject(e)))
        .on('data', d => console.log(opts, 'to:'+whichserver, 'read', d.toString()))
        .on('end', () => resolve());
}))).flat();

Promise.all(serversReady())
    .then(servers => Promise.allSettled(clientsDone()).then(() => servers))
    .then(servers => servers.forEach(s => s.close()));

问题解答 #

1. Node.js 16.13.1到17.7.2之间网络模块的相关变更 #

核心是Node.js从17.0.0版本开始调整了localhost的DNS解析规则：16及之前版本默认强制IPv4地址优先，解析localhost时会优先选用127.0.0.1建立连接；17版本开始取消了这个强制优先级规则，完全按照操作系统本地的DNS解析返回顺序选择连接地址。
Windows默认配置下，localhost解析会先返回IPv6环回地址::1，再返回IPv4的127.0.0.1。Node.js 17拿到第一个返回的::1就直接走IPv6环回接口发起连接，而绑定0.0.0.0的服务只监听IPv4栈的所有地址，根本没监听IPv6的::1端口，自然返回ECONNREFUSED错误。

2. 该连接异常是版本Bug还是官方有意做出的破坏性调整？ #

是官方主动推出的破坏性变更，不属于Bug。这个调整是为了对齐通用网络标准规范，让DNS解析行为和系统默认行为保持一致，17版本的更新日志中已经将该变更列入不兼容更新条目，只是没有专门针对本地TCP连接场景的兼容性影响做足够明确的提示，导致大量开发者升级版本后踩坑。

3. 是否存在无需全局替换localhost为0.0.0.0的配置方案，可恢复原有的连接行为？ #

不需要全量修改业务代码替换localhost，两种无侵入方案即可完全恢复16版本的连接行为：

• 启动Node.js进程时添加--dns-result-order=ipv4first启动参数，强制DNS解析结果IPv4优先，和16及之前版本的行为完全一致。如果不想逐个修改服务启动命令，可以把这个参数配置到系统的NODE_OPTIONS环境变量中，所有Node.js进程启动时会自动加载该配置。
• 如果允许修改少量入口代码，直接在项目入口文件的最顶部添加网络配置：ESM项目写import net from 'net'; net.setDefaultAutoSelectFamily(false)，CommonJS项目写require('net').setDefaultAutoSelectFamily(false)。这个API从Node.js 17.3.0版本开始支持，关闭自动地址族选择逻辑后，就会恢复旧版优先尝试IPv4连接的行为。

补充说明：Node.js 18、19、20所有后续大版本都保留了17版本引入的这个默认解析规则，后续升级大版本时同样需要注意该兼容性问题。

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