node.js 必须正确安装并配置环境变量，运行 node -v 和 npm -v 能输出版本号（如 v20.15.0），否则 vscode 无法运行 node 进程；推荐安装 lts 版并勾选“add to path”，重启终端和 vscode 后验证。
确认 Node.js 已正确安装并可用
没装好 node 或 npm，后面所有步骤都会卡在第一步。运行 node -v 和 npm -v 必须输出版本号（比如 v20.15.0），否则 VSCode 里跑不起来任何 Node 进程。
常见错误现象：
-
command not found: node或'node' is not recognized as an internal or external command—— 说明环境变量没配好，不是 VSCode 的问题，是系统级缺失 - VSCode 终端里能运行
node -v，但外部 CMD/PowerShell 里不行 —— VSCode 启动时继承了用户会话 PATH，但系统未全局生效，调试或脚本调用时可能失败
建议直接重装 Node.js LTS 版（当前是 v20.15.0），勾选 “Add to PATH” 选项；若已装过，重启终端 + 重启 VSCode 再验证。
用 ws 库快速启动 WebSocket 服务
别用过时的 nodejs-websocket 或封装过度的 socket.io（除非你真需要它的房间、广播、自动降级等特性）。纯 WebSocket 实时通信，ws 库最轻、最标准、出错反馈最直接。
实操建议：
- 在项目根目录运行
npm init -y初始化package.json - 执行
npm install ws安装依赖 - 新建
server.js，内容如下：
const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 8080 });
wss.on('connection', (ws) => {
console.log('✅ 客户端已连接');
ws.send('欢迎接入 WebSocket 服务');
ws.on('message', (data) => {
console.log('? 收到:', data.toString());
ws.send(`回传: ${data}`);
});
ws.on('close', () => console.log('❌ 连接关闭'));
});
运行 node server.js 后，服务就起来了。注意端口别被占用：可先执行 lsof -i :8080（macOS/Linux）或 netstat -ano | findstr :8080（Windows）检查。
VSCode 中调试 WebSocket 服务的关键配置
直接用终端跑 node server.js 没法打断点、看变量、查调用栈。要真正调试，必须配 .vscode/launch.json。
关键点：
- 不要用
attach模式去连一个已运行的进程（容易连错端口或超时） - 推荐用
launch模式，设"program": "./server.js"，并加"console": "integratedTerminal"方便看到日志 - 如果断点不触发，检查是否启用了 JavaScript 调试器（VSCode 1.80+ 默认启用；旧版需禁用旧调试器，在设置里搜
debug.javascript.usePreview设为true）
最小可用配置示例：
{
"version": "0.2.0",
"configurations": [
{
"type": "pwa-node",
"request": "launch",
"name": "Launch WebSocket Server",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/server.js",
"console": "integratedTerminal"
}
]
}</node_internals>
客户端 HTML 测试页别硬写原生 WebSocket API
手写 new WebSocket('ws://localhost:8080') 容易漏掉 onerror、onclose 处理，连接失败时控制台静默，你以为服务没起来，其实是前端没报错。
更稳妥的做法：
- 新建
client.html，用简单状态标记连接状态（比如页面顶部显示connecting → open → closed） - 加个
console.log打印所有事件，尤其是onerror回调 —— 很多连接失败（如跨域、端口错、服务未启）都走这里 - 别用 Live Server 插件直接打开 HTML（它起的是 HTTP 服务，协议是
http://，而 WebSocket 需要同源或显式指定ws://）—— 直接双击打开或用浏览器地址栏输file:///xxx/client.html即可
精简测试页片段：
<script>
const socket = new WebSocket('ws://localhost:8080');
socket.onopen = () => console.log('? open');
socket.onerror = e => console.log('? error:', e);
socket.onclose = () => console.log('⚪ close');
socket.onmessage = e => console.log('?', e.data);
</script>
WebSocket 不是“装完插件点一下就通”的功能，它的成败往往卡在端口、协议、事件监听完整性这些细节上。尤其注意：服务端改了代码后必须重启进程（ws 不支持热更新），而客户端 HTML 页面每次修改后必须硬刷新（Ctrl+F5），否则旧连接缓存可能干扰测试。
