VSCode调试Node.js应用失败的五大解决方案：配置launch.json、集成nodemon热重载、附加到运行进程、启用source map支持TS调试、验证连接与修复环境。
如果您正在使用 Visual Studio Code 开发 Node.js 后端应用，但无法启动调试会话或断点不生效，则可能是由于 launch.json 配置错误、运行时环境不匹配或源码映射未正确启用。以下是实现稳定调试的多种方法：
本文运行环境：MacBook Air，macOS Sequoia。
一、配置 launch.json 启动项
VSCode 通过 .vscode/launch.json 文件定义调试行为，需为 Node.js 环境指定正确的程序入口、运行模式及源码映射选项。
1、在项目根目录下创建 .vscode 文件夹（若不存在）。
2、在该文件夹中新建 launch.json 文件。
3、写入以下内容，确保 program 字段指向主入口文件（如 index.js 或 app.js）：
4、{"version": "0.2.0","configurations": [{"type": "node","request": "launch","name": "Launch Program","skipFiles": ["
5、保存后按 Ctrl+Shift+D（Windows/Linux）或 Cmd+Shift+D（macOS）打开调试面板，选择 “Launch Program” 并点击绿色三角形启动。
二、使用 nodemon 实现热重载调试
在开发过程中频繁手动重启进程效率低下，通过集成 nodemon 可监听文件变化并自动重启调试会话，同时保持断点可用性。
1、全局或本地安装 nodemon：npm install --save-dev nodemon。
2、修改 launch.json 中的 configuration，将 type 改为 node，添加 runtimeExecutable 和 runtimeArgs 字段：
3、"runtimeExecutable": "${workspaceFolder}/node_modules/.bin/nodemon","runtimeArgs": ["--inspect-brk", "${workspaceFolder}/index.js"]
4、确保 package.json 的 scripts 中包含 "debug": "nodemon --inspect-brk index.js"（可选备用方式）。
5、启动调试时，VSCode 将自动附加到 nodemon 启动的带调试端口的 Node 进程。
三、附加到已运行的 Node 进程
当服务已在终端中通过 node --inspect 启动时，VSCode 可以主动连接该进程进行调试，适用于 Docker 容器或 PM2 等托管场景。
1、在终端中运行：node --inspect=9229 index.js（端口可自定义）。
MiniMax 图片理解 + 网络搜索 MCP 工具。适配 Docker 环境（极空间等），支持图片 OCR 识别、图像内容理解、网络搜索。API Key 安全存储在本地 credentials 文件，不暴露在代码中。
2、确认控制台输出类似 “Debugger listening on ws://127.0.0.1:9229/...”。
3、在 launch.json 中新增一个 configuration：
4、{"type": "node","request": "attach","name": "Attach to Process","port": 9229,"address": "localhost","localRoot": "${workspaceFolder}","remoteRoot": "${workspaceFolder}"}
5、启动该配置，VSCode 将连接至正在监听 9229 端口的 Node 实例。
四、启用 source map 支持 TypeScript 调试
若项目使用 TypeScript 编写，需生成 source map 文件并将调试器指向原始 TS 源码，而非编译后的 JS 输出目录。
1、确保 tsconfig.json 中包含 "sourceMap": true 和 "outDir": "./dist"。
2、编译项目：tsc，检查 dist 目录下是否生成 .js.map 文件。
3、在 launch.json 中设置 program 为编译后路径（如 "${workspaceFolder}/dist/index.js"），并添加 "sourceMaps": true 和 "outFiles": ["${workspaceFolder}/dist/**/*.js"]。
4、在 TypeScript 源文件（如 src/index.ts）中设置断点，启动调试后断点将自动映射并命中。
五、验证调试器连接状态与常见修复
VSCode 调试界面右上角显示当前会话状态，若出现 “No active debug session” 或 “Cannot connect to runtime process” 提示，需逐项核查基础依赖与权限。
1、在终端执行：node -v，确认 Node.js 版本 ≥ 14.x（推荐 18.x 或 20.x）。
2、检查 VSCode 已安装官方 Node.js Extension Pack（含 Debugger for Node.js）。
3、关闭所有其他占用 9229 端口的进程：lsof -i :9229 | grep LISTEN | awk '{print $2}' | xargs kill -9（macOS/Linux）。
4、禁用所有非必要 VSCode 扩展，排除插件冲突导致的调试中断。
5、在项目根目录下运行 code --disable-extensions . 以纯净模式重新打开工作区。
