VSCode调试Node.js断点不生效，八成因node未进环境变量或program路径错误；需在VSCode终端验证node -v，确保PATH正确，并使program指向真实可执行JS文件（如"${workspaceFolder}/dist/index.js"）。
VSCode 调试 Node.js 断点不生效？八成是 node 命令根本没进 VSCode 的环境变量，或者 program 路径写错了——这两点不解决，配再复杂的 launch.json 都白搭。
node 命令在 VSCode 终端里能用，但调试器报 “Cannot find runtime 'node' on PATH”
这不是 VSCode 插件问题，而是它启动时没加载你的 shell 初始化文件（比如 ~/.zshrc 或 ~/.bash_profile），PATH 里压根没有 node。
- macOS/Linux：检查
~/.zshrc是否有export PATH="/usr/local/bin:$PATH"（Homebrew 安装路径）；没有就加上，然后运行source ~/.zshrc，再彻底退出 VSCode 所有进程，重新从终端启动：code . - Windows：重装 Node.js，务必勾选 “Add to PATH”；或手动把
C:\Program Files\nodejs\加进系统环境变量 - 验证方式：在 VSCode 内置终端（
Ctrl + `）里执行node -v，必须有输出；如果终端里有、调试器里报错，说明调试器根本没读到这个 PATH
断点全灰、点不进去，program 字段最容易写错
program 必须是相对于工作区根目录的、真实存在的可执行 JS 文件路径。它不是相对路径语法，也不是命令行参数，更不能指向源码（如 .ts）。
- 正确写法：
"program": "${workspaceFolder}/src/index.js"（推荐用变量，避免硬编码） - 错误写法：
"program": "src/index.js"（缺${workspaceFolder}/，VSCode 找不到） - 错误写法：
"program": "./src/index.js"（.在这里不被解析，等同字面量） - TypeScript 项目：别写
src/index.ts；要么编译后指向dist/index.js，要么用preLaunchTask触发tsc编译 - ESM 项目：必须在
package.json里加"type": "module"，否则import解析失败，连require都会报Cannot find module
Express/Koa 服务一调试就卡住或报 EADDRINUSE
用 launch 模式硬启服务，容易和环境变量、子进程、端口监听冲突。attach 模式才是生产级调试的常规操作。
- 先在终端手动跑：
node --inspect-brk ./bin/www（停在第一行，留出连接窗口） -
launch.json配置关键项："type": "node"、"request": "attach"、"port": 9229 - 如果用了自定义端口，比如
--inspect=9230，port值必须同步改，否则连不上 - 别同时起两个
--inspect进程——端口冲突会导致第二个报Starting inspector on 127.0.0.1:9229 failed: address already in use
调试时变量显示为 undefined，或断点停在编译后代码上
这是 source map 没对上，不是代码逻辑问题。尤其 TypeScript、Webpack、Babel 项目极易踩坑。
- TypeScript：确认
tsconfig.json开启了"sourceMap": true和"inlineSources": true（后者让源码嵌进 map，省去额外加载） - Webpack：
devtool设为"source-map"或"inline-source-map"，避免用"eval"类型（VSCode 不识别） - 检查生成的
.js.map文件是否和对应.js同目录，且sources字段里的路径是相对路径（绝对路径容易 404） - 如果用了
ts-node，别在program里直接指.ts；应设"runtimeExecutable": "npx"，"runtimeArgs": ["ts-node", "${workspaceFolder}/src/index.ts"]
最常被忽略的一点：VSCode 启动后改了环境变量，必须彻底退出重开，它不会自动刷新 PATH；而 program 路径一旦写错，断点就永远是灰色的——哪怕你重启十次，也看不出哪里不对。
