VS Code 调试 Node.js 需正确配置 launch.json，否则断点不生效、console.log 无输出、process.env 读不到环境变量；须确认 node 全局可用且 ≥14，显式设置 runtimeExecutable、env 和 console，并注意 Express/TS 的特殊配置要求。
VS Code 调试 Node.js 不需要额外装插件，但必须正确配置 launch.json，否则断点不生效、console.log 看不到输出、process.env 读不到环境变量——这些是新手最常卡住的三个点。
确认 Node.js 已全局可用且版本 ≥ 14
VS Code 的调试器依赖系统 PATH 中的 node 命令。如果终端里能运行 node -v，但 VS Code 启动调试时报 “command 'node' not found”，大概率是 VS Code 没继承 shell 的环境（尤其在 macOS 或 Linux 下用 zsh 启动时）。
- 在终端中执行
which node，复制路径（如/opt/homebrew/bin/node） - 打开 VS Code 设置（
Cmd+, / Ctrl+,），搜索debug.node.autoAttach，确保为on（方便直接 F5 启动） - 若仍失败，在
.vscode/settings.json中显式指定："terminal.integrated.defaultProfile.osx": "zsh",
"terminal.integrated.env.osx": { "PATH": "/opt/homebrew/bin:${env:PATH}" }
生成正确的 launch.json 配置
别手写 launch.json —— VS Code 提供的自动引导容易漏掉关键字段。点击「运行」→「打开启动配置」→ 选 Node.js，它会生成基础模板，但以下三项必须手动补全：
-
runtimeExecutable：指向你实际使用的node（尤其当你用nvm切换版本时），例如："runtimeExecutable": "/Users/you/.nvm/versions/node/v18.18.2/bin/node"
-
env：环境变量不能靠.env文件自动加载，必须显式写进配置，比如："env": { "NODE_ENV": "development", "PORT": "3001" } -
console：默认integratedTerminal可能吞掉某些日志，改成externalTerminal更可靠（macOS 下会弹出 Terminal.app）
调试 Express/Koa 等 Web 应用时的断点陷阱
Express 启动后代码才执行，但 VS Code 默认在入口文件第一行就暂停（program 模式）。如果你在路由处理函数里打断点却从不触发，问题往往出在启动方式上：
- 不要用
nodemon直接替换node—— 它是子进程，调试器抓不到。改用nodemon --inspect+ VS Code 的attach模式 - 推荐用
run模式配合--inspect-brk参数："configurations": [{
"type": "node",
"request": "launch",
"name": "Launch Express",
"program": "${workspaceFolder}/app.js",
"args": ["--inspect-brk"],
"skipFiles": [""]
}] -
skipFiles必须加，否则断点会停在internal/modules/cjs/loader.js这类内部文件里
调试 TypeScript 项目要多走两步
TS 编译后的 JS 才是 Node 执行的，所以源码映射（source map）必须存在且被识别。光有 tsconfig.json 里的 "sourceMap": true 不够：
- 确保
tsc已运行过（或开启watch），输出目录（如dist/）下有.js.map文件 -
launch.json中的program必须指向编译后的 JS 入口（如dist/index.js），不是src/index.ts - 加
outFiles字段帮助定位："outFiles": ["${workspaceFolder}/dist/**/*.js"] - 如果用
ts-node直接跑 TS，调试需用node类型 +runtimeArgs："runtimeArgs": ["-r", "ts-node/register"],
"args": ["${workspaceFolder}/src/index.ts"]
真正卡住人的从来不是“怎么配”，而是“为什么配了还不生效”——多数时候是 runtimeExecutable 指向了旧版本 Node，或 env 漏写了某个关键变量，又或者 outFiles 路径没匹配到生成的 map 文件。盯住调试控制台左下角的「已连接」状态和右上角的「断点验证」图标，比反复重启更省时间。
