因为浏览器只支持标准 WebSocket 协议（RFC 6455），不接受裸 TCP 连接；net 模块无法完成 HTTP 升级响应，前端 new WebSocket() 会连接失败；而 Socket.IO 封装了协议兼容、降级、心跳等能力，是稳妥选择。
为什么 net 模块不能直接替代 socket.io 做 Web 实时通讯
直接用 Node.js 原生 net 或 http 模块搭 TCP 服务，浏览器连不上。因为浏览器的 WebSocket API 不接受裸 TCP 连接，也不支持自定义协议握手；它只认标准 ws:// 或 wss:// 协议，且要求服务端完成 RFC 6455 定义的升级响应。你写个 net.createServer() 监听 3000 端口，前端 new WebSocket('ws://localhost:3000') 会立刻报 ERR_CONNECTION_REFUSED 或 Invalid frame header。
所以必须用兼容 WebSocket 协议栈的库，socket.io 是最稳妥的选择——它自动降级（HTTP long-polling）、处理跨域、序列化、心跳、重连，而且和 VSCode 开发流程零冲突。
VSCode 中启动 Socket.IO 服务的最小可运行配置
不需要插件，不改 VSCode 设置。只要确保本地有 node 和 npm，在项目根目录执行：
npm init -y npm install socket.io
新建 server.js：
const http = require('http');
const { Server } = require('socket.io');
const server = http.createServer();
const io = new Server(server, {
cors: {
origin: 'http://localhost:5173', // 对应你的前端地址，Vite 默认是这个
methods: ['GET', 'POST']
}
});
io.on('connection', (socket) => {
console.log('客户端已连接:', socket.id);
socket.emit('welcome', { msg: '欢迎加入' });
socket.on('chat', (data) => {
io.emit('broadcast', data); // 广播给所有人
});
});
server.listen(3000, () => {
console.log('Socket.IO 服务运行在 http://localhost:3000');
});
在 VSCode 终端里运行：node server.js。别用 nodemon 自动重启？可以，但注意：每次重启 socket.id 全失效，前端要处理断连重连逻辑。
前端连接失败的三个高频原因及对应检查点
常见现象：控制台报 WebSocket connection to 'ws://localhost:3000/socket.io/?EIO=4&transport=websocket' failed，或一直 fallback 到 polling。
详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。
-
后端没开 CORS：确认
server.js中cors.origin和前端实际地址（含端口）完全一致，比如用 Vite 启的是5173，React Create App 是3000，别写成*（开发期可临时用，但某些浏览器策略会拒绝） -
前端 SDK 版本和服务端不匹配：查
package.json里socket.io和socket.io-client是否同为^4.7.5这类 v4.x 版本。v3 和 v4 不兼容，v4 客户端连 v3 服务端会卡在 handshake 阶段 -
路径被代理劫持：如果你用 Nginx 或 Vite 的
proxy，确保没把/socket.io/路径转发错。Vite 的vite.config.ts里 proxy 规则要显式放过：'/socket.io': { target: 'http://localhost:3000', ws: true }
调试时怎么快速验证消息是否真正发出/收到
别只看 console.log，Socket.IO 的事件监听容易漏掉拼写错误或作用域问题。建议在前后端都加基础日志：
后端加一句：socket.onAny((event, ...args) => console.log('[SOCKET IN]', event, args));
前端加一句：socket.onAny((event, ...args) => console.log('[SOCKET OUT]', event, args));
这样只要一收一发，终端立刻对得上。如果后端有 log、前端没 log，说明连接根本没建好；如果前端有 log、后端没 log，大概率是 emit 写错了事件名（比如写了 chatMsg，监听却写成 message），或者 socket 实例被重复创建覆盖了。
另外，VSCode 的「Terminal」面板别关太多，保留一个跑 node server.js，另一个跑前端 npm run dev，出问题时两眼就能对齐时间戳和错误行。
真实项目里，socket.io 的命名空间、房间、中间件、适配器这些功能很容易堆叠复杂度，但起步阶段就盯死三件事：连接通不通、事件名对不对、CORS 放没放对——其他都是锦上添花。
