VSCode调试NestJS WebSocket服务的关键是正确配置npm脚本启动、端口一致、sourceMap路径对齐及避免调试器劫持upgrade请求，需启用cors、显式引入网关、分离HTTP/WS端口并先启服务再启客户端。
VSCode 调试 NestJS 的 WebSocket 服务，关键不是“配 Node 环境”，而是让 nest start:debug 启动时正确启用 --inspect 并暴露调试端口，同时确保 WebSocket 连接不被调试器阻断或超时。直接改 launch.json 就能跑通，但容易卡在连接建立阶段——因为默认调试模式会暂停未命中断点的进程，而 WebSocket 升级请求常被忽略。
确认 NestJS 项目已启用 WebSocket 模块
NestJS 的 @nestjs/websockets 不是开箱即用的：它依赖底层 HTTP 服务（如 Express/Fastify）复用同一端口处理升级请求。如果你用的是默认的 Express 平台，必须显式启用 cors 和 upgrade 事件监听，否则客户端连不上。
- 检查
main.ts中是否调用了app.enableCors()（WebSocket 握手跨域必需） - 确保
NestFactory.create(AppModule, new ExpressAdapter())或类似适配器已正确传入，而非裸用createHttpServer - WebSocket 网关类（
@WebSocketGateway()）必须被AppModule的providers或imports显式引入，否则模块不会初始化
launch.json 必须用 npm script 启动，不能直接指向 main.js
直接运行 main.js 会绕过 nest-cli 的编译流程和调试参数注入，导致 TypeScript 源码无法映射、断点失效，且 WebSocket 升级头可能被丢弃。NestJS 官方推荐通过 npm run start:debug 启动，并在 package.json 中定义该脚本：
提供端到端的高端代理设置和使用指导，包括代理类型选择、地区定向、访问配置、API密钥验证和监控。
"scripts": {
"start:debug": "nest start --debug --watch"
}
对应 launch.json 配置应为：
{
"type": "node",
"request": "launch",
"name": "Debug NestJS WebSocket",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "start:debug"],
"port": 9229,
"console": "integratedTerminal",
"internalConsoleOptions": "neverOpen",
"restart": true,
"sourceMaps": true,
"outFiles": ["${workspaceFolder}/dist/**/*.js"]
}
-
port必须与--debug参数默认端口一致（9229），若改了需同步调整 -
outFiles是关键：没有它，VSCode 找不到生成的.js文件，断点永远灰掉 - 不要设
stopOnEntry，否则进程一启动就挂起，WebSocket 客户端收不到响应
WebSocket 连接失败时先检查调试器是否劫持了 upgrade 请求
VSCode 内置调试器在监听 http 请求时，偶尔会拦截 Upgrade: websocket 头并静默丢弃，现象是客户端一直 pending，服务端 handleConnection 完全不触发。这不是代码问题，而是调试器行为。
- 临时验证方式：终端手动执行
npm run start:debug，再用浏览器或wscat连接ws://localhost:3000—— 如果能通，说明是 VSCode 调试配置问题 - 根本解法：在
launch.json中加"skipFiles": ["<node_internals>/**"]</node_internals>，避免调试器进入底层 HTTP 模块干扰 upgrade 流程 - 更稳妥的做法是把 WebSocket 端口和 HTTP 端口分离（例如 HTTP 用 3000，WS 用 3001），并在
main.ts中用app.useWebSocketAdapter(new WsAdapter(app.getHttpServer()))显式绑定，减少复用冲突
最常被忽略的一点：NestJS 的 WebSocket 网关默认不自动重连，客户端首次连接失败后，VSCode 断点停住期间，前端可能已放弃重试；等你继续执行，服务端才开始监听，但客户端不再发新请求。所以调试时，先启服务，再启客户端，别反过来。
