VSCode断点调试在单文件JS时可自动生成配置，但多环境、多入口、带参数、TypeScript或附加进程等场景必须手动配置launch.json；最小配置需含version、type、request、name和绝对路径program。
VSCode 的断点调试不依赖 launch.json 也能启动，但绝大多数真实项目（尤其是多环境、多入口、带参数或需附加进程的场景）必须靠它精准控制调试行为。盲目复制网上的模板反而容易触发 Cannot find runtime 'node' on PATH 或 Program path does not exist 这类错误。
什么时候必须手动配置 launch.json
不是所有项目都需要它：单文件 JS 直接按 F5，VSCode 会自动生成临时配置；但以下情况必须编辑 .vscode/launch.json：
- 入口文件不是
index.js或不在项目根目录（比如src/cli.js） - 需要传命令行参数（如
--env=dev）或设置环境变量（NODE_ENV=production） - 调试 TypeScript 项目（需指定
outFiles或启用sourceMaps） - 附加（attach）到已运行的 Node 进程（如本地启动的 Express 服务）
- 调试 Web 应用时需同时启动浏览器并自动打开 URL
launch.json 最小可用配置长什么样
以调试一个 src/app.js 的 Node 脚本为例，这是去掉所有可选字段后的最简有效配置：
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Launch app.js",
"skipFiles": ["<node_internals>/**"],
"program": "${workspaceFolder}/src/app.js"
}
]
}
关键点：
-
"type": "node"表示使用 Node.js 调试器；如果是 Chrome 调试前端，这里得是"pwa-chrome" -
"request": "launch"表示“启动新进程”，对应"request": "attach"是连接已有进程 -
"program"必须是绝对路径，${workspaceFolder}是唯一安全的变量；写相对路径（如"./src/app.js"）在某些工作区结构下会失败 -
"skipFiles"不是必须，但强烈建议加上，否则调试时会频繁跳进 Node 内部代码
常见报错和对应修复项
这些错误几乎都源于路径、类型或运行时上下文不匹配：
-
Cannot find runtime 'node' on PATH→ 检查系统是否安装 Node，且 VSCode 终端里执行which node（macOS/Linux）或where node（Windows）能返回路径；若用 nvm/nodenv，需在 VSCode 外部终端中启动 VSCode（如code .），而非从 Dock 或开始菜单直接打开 -
Program path does not exist→ 把"program"值粘贴到终端执行ls -l [路径]验证是否存在；注意 Windows 路径分隔符不用反斜杠（），统一用正斜杠（/）或双反斜杠（\） - 断点显示为空心圆（未绑定）→ 检查是否启用了 source map：TypeScript 项目需确保
tsconfig.json中"sourceMap": true，且launch.json中添加"sourceMaps": true和"outFiles": ["${workspaceFolder}/dist/**/*.js"] - 调试时控制台无输出 / 输出乱码 → 在
launch.json中加"console": "integratedTerminal"，强制输出到集成终端而非调试控制台
真正难的不是写对配置，而是理解每个字段背后绑定的运行时行为——比如 cwd 控制的是 process.cwd()，而 env 设置的是子进程环境变量，这两者错位会导致 require 路径失败或 dotenv 加载不到文件。改完配置别急着点绿色三角，先看右下角调试面板里显示的完整启动命令，它比任何文档都诚实。
