VSCode调试Node.js失败90%因node未被识别：需先在内置终端执行node -v/npm -v验证，macOS/Linux须用code .启动以加载shell配置，Windows需勾选Add to PATH或手动添加安装路径；program必须指向真实.js文件，TS/ESM项目需额外配置编译或type字段。
VSCode 调试 Node.js 失败，90% 不是 launch.json 写错了，而是 node 命令根本没被识别——VSCode 内置终端不自动继承 shell 环境变量，PATH 配置对它无效。
确认 node 和 npm 在 VSCode 终端里能用
这是所有调试的前提，跳过这步后面全白搭。
- 打开 VSCode 内置终端（
Ctrl + `），直接输入node -v和npm -v - macOS/Linux：如果报
command not found，别从 Dock 或 Spotlight 启动 VSCode；必须在终端里执行code .启动，否则~/.zshrc或~/.bash_profile不生效 - Windows：安装 Node.js 时没勾选 “Add to PATH”，就手动把 Node 安装路径（如
C:\Program Files\nodejs\）加进系统环境变量的PATH - 用
nvm的用户：确保当前终端已执行nvm use，且 VSCode 是从该终端启动的；否则可在.vscode/settings.json中硬编码："runtimeExecutable": "/Users/you/.nvm/versions/node/v18.17.0/bin/node"
program 字段必须指向真实存在的 .js 文件
断点变空心、提示 Cannot launch program，基本就是这个字段写错了。
OpenGemini Next.js Bestpractice Builder
下载
使用固定的 Next.js/Tailwind/Prisma 技术栈构建并记录独立 SaaS 项目，仅将 FastAPI 用于 Python 工作负载，并遵循严格的架构规范。
- 正确写法：
"program": "${workspaceFolder}/src/index.js"（推荐，跨平台安全） - 错误写法：
"program": "src/index.js"（缺${workspaceFolder}/，VSCode 不会自动补前缀） - 错误写法：
"program": "./src/index.js"（.在这里不解析，等同于字面量字符串） - TypeScript 项目别直接指
src/index.ts：要么配preLaunchTask编译到dist/后指向dist/index.js，要么改用runtimeExecutable: "npx"+runtimeArgs: ["ts-node", "src/index.ts"] - ESM 项目调试时报
Cannot use import statement outside a module：不是语法错，是 Node 默认按 CommonJS 解析；必须在package.json根目录显式声明"type": "module"
前端项目别用 launch 模式直接跑 JS 文件
Vite、Webpack Dev Server 这类开发服务器本身是 npm 脚本封装的，不是单个 JS 文件，硬指 program 会失败。
- 先验证：在 VSCode 终端里运行
npm run dev能否正常启动服务 - 确保
package.json里有有效脚本，比如"dev": "vite"或"start": "react-scripts start" - 配置
launch.json时，用runtimeExecutable指向npm，再用runtimeArgs传参："runtimeExecutable": "npm"，"runtimeArgs": ["run", "dev"] - 若需调试源码（TS 或 JSX），必须开启
sourceMaps：在launch.json对应配置中加"sourceMaps": true，并设"outFiles": ["${workspaceFolder}/dist/**/*.js"]（路径按实际构建输出调整）
attach 模式比 launch 更可靠，尤其对复杂启动流程
很多框架（如 NestJS、某些 Express 启动方式）内部会 fork 子进程或延迟加载，launch 模式容易错过断点。
- 启动服务时加
--inspect-brk参数：比如node --inspect-brk ./dist/main.js，进程会在第一行暂停等待调试器连接 -
launch.json配置"request": "attach"，指定"port": 9229（默认值），不填program - 更省事的办法：启用 VSCode 的 Auto Attach 功能（命令面板搜
Toggle Auto Attach），然后在终端里直接运行node --inspect-brk index.js，VSCode 会自动接管 - 注意端口冲突：多个 Node 进程同时用
--inspect可能抢 9229 端口，可手动指定其他端口，如--inspect=9230，并在launch.json中同步改port
最常被忽略的其实是启动方式——双击打开的 VSCode 和终端里 code . 启动的，环境变量完全两套逻辑；哪怕 node -v 在系统终端能跑，也不代表它在 VSCode 里可用。这点不确认清楚，后面所有配置都是空中楼阁。
