能够成功运行 node 命令，并且 VSCode 支持断点调试，才算真正完成了 Node.js 开发环境配置——其余插件、代码格式化、TypeScript 支持等都属于锦上添花，并非必需项。
验证 Node.js 与 npm 是否真正可用（切勿跳过此步骤）
很多人在此处遇到困难，却误以为是 VSCode 设置问题。请打开系统终端（非 VSCode 内置终端），执行以下命令：
node -v npm -v
如果出现错误提示 'node' 不是内部或外部命令，说明 Node.js 未正确添加到系统 PATH 环境变量。安装 LTS 版本时务必勾选 Add to PATH；若遗漏了，需手动将 Node.js 安装目录（如 C:\Program Files\nodejs）添加到系统环境变量 Path 中，然后彻底关闭 VSCode 进程后重新启动。
- Windows 用户：确保路径中不包含中文或空格（例如
D:\我的软件\nodejs），否则npm可能静默失败而不报错 - macOS/Linux 用户推荐使用
nvm管理版本：确认source ~/.nvm/nvm.sh已写入~/.zshrc或~/.bash_profile，且新终端已加载配置 npm -v必须成功执行——VSCode 调试器底层依赖npm启动脚本，这是刚性需求，非可选
VSCode 内置调试器开箱即用，无需额外插件
确认 node 可用后，仅需三个步骤：
- 创建一个新的项目文件夹，在其中新建
index.js文件，写入一行代码console.log('ok'); - 按下
Ctrl+Shift+P（macOS 为Cmd+Shift+P），输入Debug: Open Configuration，选择Node.js → Current File - VSCode 会自动生成
.vscode/launch.json配置文件，其中包含"program": "${file}"—— 表示“运行当前打开的 JS 文件”
此时，在代码行号左侧单击设置断点，按 F5 即可启动调试。如果出现 Cannot find runtime 'node' 错误，那一定是第一步的 Node.js 环境未正确配置，而非 VSCode 设置问题。
launch.json 中的常见配置陷阱与解决方案
默认生成的配置适用于单文件调试，但在实际开发中常遇到以下问题：
- 需要调试
npm start命令？将"program"改为"npm"，"args"设为["start"]，并添加"console": "integratedTerminal"，否则无法看到npm的输出信息 - 使用
nodemon实现热重载？不能直接在launch.json中调用nodemon—— VSCode 调试器不支持进程的热替换，必须采用attach模式：
先在命令行执行nodemon --inspect-brk index.js，再在launch.json中配置"type": "node"+"request": "attach"+"port": 9229 - 本地存在多个 Node.js 版本（例如通过
nvm管理）？显式指定"runtimeExecutable"，例如："runtimeExecutable": "/usr/local/bin/node"（macOS/Linux）或"runtimeExecutable": "C:\nodejs\node.exe"（Windows），否则 VSCode 可能调用错误的版本
避免使用 code-runner 直接运行 JS 文件
它看似一键运行，实际上绕过了 Node.js 调试器，会导致以下三类问题：
- 断点完全失效 —— 因为并非通过 VSCode 的 debugger 启动进程
- 中文路径或包含
import的 ES Module 文件直接报错 —— 它默认使用node $fileName，未添加--experimental-specifier-resolution=node参数 - 交互式脚本（如
readline）卡死 ——code-runner不支持stdin输入流
推荐替代方案：改用 VSCode 自带的调试模式（F5），或在终端中手动执行 node --experimental-specifier-resolution=node index.js。
真正省心的从零开始配置，是将环境变量、package.json、.vscode/launch.json 以及 tsconfig.json（如果使用 TypeScript）这四样全部配齐；缺少任何一个，后续都会反复踩坑。最容易忽略的是：VSCode 启动时未加载 Shell 环境变量，导致内置终端与系统终端行为不一致——验证方法是在 VSCode 内置终端中运行 echo $PATH（macOS/Linux）或 echo %PATH%（Windows），检查输出中是否包含 node 所在的目录。
