Vue3项目访问localhost触发Node Socket警告，--host访问正常的排查与解决

问题背景 #

我通过以下选项创建了一个新的Vue 3项目：

npm create vue@latest

✔ Add TypeScript? … Yes
✔ Add JSX Support? … No
✔ Add Vue Router for Single Page Application development? … Yes
✔ Add Pinia for state management? … Yes
✔ Add Vitest for Unit testing? … No
✔ Add an End-to-End Testing Solution? … No
✔ Add ESLint for code quality? …  Yes
✔ Add Prettier for code formatting? … Yes

运行npm run dev后，应用正常启动：

VITE v5.0.10  ready in 300 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

但访问localhost时应用崩溃并显示如下错误：

(node:51508) Warning: An error event has already been emitted on the socket. Please use the destroy method on the socket while handling a 'clientError' event.
(Use `node --trace-warnings ...` to show where the warning was created)

使用--host参数启动应用时，显示如下信息：

VITE v5.0.10  ready in 295 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://xxx.xxx.xx.xx:5173/
  ➜  Network: http://xxx.xxx.xx.xx:5173/
  ➜  Network: http://xxx.xxx.xx.xx:5173/
  ➜  press h + enter to show help

此时访问任一网络地址均正常。我当前使用Node 20.10.0 64bit，且已尝试多个Node版本但问题依旧。

问题 #

1. 如何调试该问题？
2. 若熟悉此错误，该如何解决？

调试方案 #

• 启用警告追踪：按照提示用node --trace-warnings命令启动项目，修改package.json里的dev脚本：

  "scripts": {
    "dev": "node --trace-warnings node_modules/vite/bin/vite.js"
  }
  

  运行npm run dev后会输出警告的完整调用栈，定位具体触发错误的代码位置。
• 验证本地IP访问：尝试访问127.0.0.1:5173，若正常则说明localhost的DNS解析存在异常，检查系统hosts文件（Windows：C:\Windows\System32\drivers\etc\hosts；Linux/macOS：/etc/hosts）中127.0.0.1 localhost的配置是否正确。
• 排查端口与代理干扰：用netstat -ano | findstr :5173（Windows）或lsof -i :5173（Linux/macOS）检查端口占用情况；关闭本地VPN、代理软件，测试是否是代理工具干扰了localhost请求。
• 简化项目排查：创建仅包含TypeScript、ESLint、Prettier的基础Vue项目，或暂时移除Vue Router、Pinia等插件，逐步定位是否是依赖或配置冲突导致问题。

解决方案 #

1. 强制绑定127.0.0.1：修改vite.config.ts，指定server的host为127.0.0.1，绕过localhost解析：

   import { defineConfig } from 'vite'
   import vue from '@vitejs/plugin-vue'
   
   export default defineConfig({
     plugins: [vue()],
     server: {
       host: '127.0.0.1'
     }
   })
   

   启动后访问127.0.0.1:5173即可。
2. 调整hosts配置：确保hosts文件中localhost仅指向127.0.0.1，注释掉::1 localhost的配置，避免IPv6解析引发Socket问题。
3. 更换Vite版本：尝试升级Vite到最新稳定版，或降级到5.0.0版本，排查是否是当前Vite版本的Socket处理bug导致。
4. 临时禁用IPv6：在系统设置中关闭IPv6功能，测试是否能解决localhost访问异常。

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