为什么我从Node.js请求本地Kirby API时出现ECONNREFUSED错误？

网络层排查（优先解决，ECONNREFUSED为连接层错误，未触达应用逻辑） #

• 确认Node服务与Kirby服务的运行网络环境是否一致：若Node服务运行在Docker、WSL、虚拟机等隔离环境中，环境内的localhost指向的是隔离环境自身，而非宿主机的8000端口，自然无法连通。可先将apiUrl替换为宿主机的局域网IP（如192.168.x.x格式）测试，验证是否为localhost解析问题。
• 核对Kirby服务的监听地址：本地开发默认启动的PHP服务通常仅绑定127.0.0.1，仅支持本地环回访问。若需要从其他网络环境访问，启动时需指定监听0.0.0.0，命令参考：php -S 0.0.0.0:8000 kirby/router.php。
• 检查端口占用与防火墙规则：确认8000端口确为Kirby服务占用，同时Node服务所在环境的防火墙未限制对8000端口的出站请求。

应用层配置排查（连接问题解决后核对） #

• 校验API路径拼接是否正确：报错信息中请求地址为http://localhost:8000/api/auth，Kirby官方API默认前缀为/api，你代码中使用${apiUrl}/auth拼接，需确认apiUrl是否已经携带/api后缀，避免拼接后路径错误。
• Basic Auth配置确认：你当前配置的basicAuth: true符合要求，后续要移除allowInsecure配置的话，仅需将API访问协议切换为HTTPS即可，本地开发可使用自签证书，生产环境配置正规SSL证书后即可安全移除该配置。
• 增加完整日志打印排查：测试阶段可补充请求参数打印，确认代码发起的请求地址、请求头和浏览器访问的完全一致，参考代码：

try {
  const fullUrl = `${apiUrl}/auth`
  console.log('请求完整地址：', fullUrl)
  const res = await fetch(fullUrl, {
    headers: {
      'Authorization': `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`,
      'Content-Type': 'application/json'
    }
  })
  const data = await res.json()
  console.log('接口返回数据：', data)
} catch (err) {
  console.error('请求错误详情：', err)
}

补充说明：浏览器可以正常访问是因为浏览器运行在宿主机桌面环境，和Kirby服务同属一个网络，可正常解析127.0.0.1:8000，和Node服务的运行环境存在差异。

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