node和npm必须在系统终端中能直接运行，否则vscode调试器必然失败；需确保安装时勾选add topath（windows）或正确配置shell初始化文件（macos/linux），并验证node-v和npm-v输出有效版本号。
node 和 npm 必须在系统终端里能直接运行
VSCode 调试器不是独立环境，它依赖系统级的 node 和 npm 命令。如果在系统终端（Windows 的 CMD/PowerShell、macOS/Linux 的 Terminal）里执行 node -v 或 npm -v 报错，VSCode 内置终端和调试功能一定失败。
常见现象：VSCode 里按 F5 提示 Cannot find runtime 'node'，或 command 'npm' not found —— 这不是 VSCode 设置问题，是环境根本没装好。
- LTS 安装包务必勾选 Add to PATH（Windows）；漏选后需手动把
C:\Program Files\nodejs加进系统环境变量Path，并重启所有终端窗口 - Windows 别装在含中文或空格路径下（如
D:\我的软件\nodejs），否则npm可能静默失败 - macOS/Linux 用
nvm的，确认source ~/.nvm/nvm.sh已写入~/.zshrc或~/.bash_profile，且新开终端已加载
项目初始化只需 npm init，不需要额外插件
VSCode 自带 Node.js 调试支持，Node.js Extension Pack 或 Debugger for Node.js 这类插件现在已过时，装了反而可能干扰调试流程。
初始化一个标准 Node.js 项目，只用三步：
- 在终端进入空文件夹，运行
npm init -y（跳过交互式提问） - 创建入口文件，比如
index.js，写一句console.log('ok'); - 在 VSCode 中打开该文件夹，按
Ctrl+Shift+P（macOS 是Cmd+Shift+P），输入Debug: Open Configuration，选Node.js → Current File
VSCode 会自动生成 .vscode/launch.json，其中 "program": "${file}" 表示运行当前打开的 JS 文件 —— 这就是最简可用的调试配置。
launch.json 配置不能照搬，得看运行方式
默认生成的 launch.json 适合单文件调试，但实际开发中常跑 npm start 或 nodemon，直接改 "program" 字段容易出错。
常见场景与对应改法：
- 想调试
npm start：把"program"改成"npm"，加"args": ["start"]，再加"console": "integratedTerminal"，否则看不到 npm 输出 - 用
nodemon热重载：不能把"program"设为nodemon—— VSCode 调试器不支持进程热替换；必须用attach模式：先终端执行nodemon --inspect-brk index.js，再在launch.json里设"type": "node"、"request": "attach"、"port": 9229 - 启动参数含空格或路径含中文：务必用双引号包裹整个路径，比如
"program": "./src/app.js"，而不是./src/app.js
断点不生效？先检查 node 版本和源码映射
即使 node -v 和 npm -v 都正常，断点也可能不命中，尤其是用 TypeScript 或打包工具（如 webpack、vite）时。
核心原因只有两个：
-
node版本太低（v14以下）或太高（某些v20+的 inspect 协议变更未被 VSCode 完全适配），建议锁定在v18.18.2或v20.15.0这类长期稳定版 - 源码映射（source map）没生成或路径不对：TypeScript 项目需确保
tsconfig.json含"sourceMap": true，且编译后.js.map文件与.js同目录；webpack 需开devtool: 'source-map'
真实调试中，launch.json 里加一行 "trace": true，然后看调试控制台输出的原始日志，比盲目查文档更快定位 source map 加载失败的位置。
