VSCode调试Node.js失败需检查launch.json配置、sourceMap启用、调试控制台使用、attach模式连接及端口占用。按步骤配置可解决断点不触发、变量不可见问题。
如果您在使用 VSCode 调试 Node.js 应用时无法成功触发断点或查看变量值，则可能是由于调试配置缺失、源码映射未启用或运行模式不匹配所致。以下是实现有效断点调试与变量实时监视的具体操作步骤：
本文运行环境：MacBook Air，macOS Sequoia。
一、配置 launch.json 启动调试任务
VSCode 依赖 .vscode/launch.json 文件定义调试会话行为，必须为 Node.js 环境显式声明程序入口、运行模式及源码映射支持，否则断点将无法绑定到原始 TypeScript 或 ES 模块代码行。
1、在项目根目录下创建 .vscode 文件夹（若不存在）。
2、在 .vscode 文件夹中新建 launch.json 文件。
3、填入以下 JSON 内容（适用于直接运行 JavaScript 文件）：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch Program",
"skipFiles": [
"
],
"program": "${file}",
"console": "integratedTerminal",
"internalConsoleOptions": "neverOpen"
4、保存文件后，打开待调试的 .js 文件，点击左侧行号区域设置断点。
二、启用 sourceMap 支持 TypeScript 或转译代码
当项目使用 TypeScript、Babel 或 Vite 构建时，实际执行的是编译后的 JavaScript，若无 sourceMap，VSCode 将无法将断点位置映射回原始源码，导致断点显示为空心圆且不生效。
1、确保 tsconfig.json 中已启用 "sourceMap": true 选项。
2、在 launch.json 的对应 configuration 中添加 "sourceMaps": true 和 "outFiles": ["${workspaceFolder}/dist/**/*.js"]（路径需按实际输出目录调整）。
3、运行 tsc 或构建命令生成带 map 文件的输出。
4、重启调试会话，验证断点是否变为实心红点。
三、使用调试控制台动态监视变量
调试控制台（Debug Console）允许在断点暂停状态下执行表达式并即时读取变量值，其作用域与当前堆栈帧一致，可替代频繁鼠标悬停操作。
根据 package.json 中的 engines 字段自动检测 Node.js 版本需求，未安装 nvm 时自动安装并切换至对应版本。支持 Windows、macOS、Linux。适用于 Node.js 项目开发、版本切换和环境配置。
1、在断点暂停时，打开 VSCode 左侧活动栏的 “运行和调试”视图。
2、点击顶部菜单栏的 “查看” → “调试控制台”，或按快捷键 Ctrl+Shift+Y（Windows/Linux）/ Cmd+Shift+Y（macOS）。
3、在控制台输入变量名（如 user.name）并回车，立即返回当前值。
4、输入 Object.keys(global) 可列出全部全局属性，辅助定位未声明变量。
四、附加到正在运行的 Node.js 进程
对于通过 npm start、nodemon 或 PM2 启动的长期进程，需采用 attach 模式而非 launch 模式，否则调试器无法连接至已有事件循环。
1、启动应用时添加 --inspect 标志，例如：node --inspect-brk app.js（--inspect-brk 表示启动即暂停）。
2、在 launch.json 中新增 configuration，设置 "request": "attach" 并指定 "port": 9229（默认端口）。
3、确保 "address": "localhost" 与本地监听地址一致。
4、在 VSCode 中选择该 configuration，点击绿色三角形启动附加调试。
五、检查调试端口占用与权限冲突
Node.js 调试协议依赖特定端口（默认 9229），若被其他进程占用或防火墙拦截，VSCode 将显示 “Cannot connect to runtime process” 错误。
1、终端执行 lsof -i :9229（macOS/Linux）或 netstat -ano | findstr :9229（Windows）确认端口占用情况。
2、若存在占用进程，记录 PID 并执行 kill -9 [PID] 强制终止。
3、在 launch.json 中临时修改端口，例如设为 "port": 9230，并在 node 启动命令中同步添加 --inspect=0.0.0.0:9230。
4、检查系统防火墙是否阻止了本地回环接口的调试通信。
