能直接在VSCode内置终端执行node -v并看到版本号才算环境真正就位；否则所有运行调试操作都会失败，必须在VSCode终端中同时验证node -v和npm -v，任一缺失即环境未就绪。
能直接在 VSCode 内置终端执行 node -v 并看到版本号，才算 Node 环境真正就位；否则所有“测试运行模块”的操作都会卡在第一步。
验证 node 是否真可用（不是看系统终端，是看 VSCode 终端）
VSCode 内置终端和系统终端的 PATH 可能不一致，尤其 macOS/Linux 下从 Dock 启动时根本不加载 ~/.zshrc。必须在 VSCode 里按 Ctrl + ` 打开终端后立刻执行：
-
node -v和npm -v都得有输出——缺一个都不算环境就绪 - 如果报
command not found: node，别调插件或改settings.json，先关掉所有 VSCode 窗口（macOS 在 Dock 右键选「退出」，Windows 在任务管理器确认Code.exe已结束），再从系统终端执行code .重启 - macOS/Linux 用户：检查
~/.zshrc是否包含source ~/.nvm/nvm.sh；Windows 用户：确认安装 Node.js 时勾选了 “Add to PATH”，或手动把C:\Program Files\nodejs\加进系统环境变量的Path
运行单个 JS 文件时，工作目录决定一切
VSCode 终端不认你当前打开的是哪个标签页，只认 shell 的当前路径（pwd 或 Get-Location）。常见错误是 node index.js 报 Cannot find module './config'，其实只是因为 cd 错了目录。
- 最稳做法：在资源管理器里右键目标文件 → 「在集成终端中运行」，VSCode 会自动
cd到该文件所在目录再执行node xxx.js - 手动执行前，先运行
pwd（macOS/Linux）或Get-Location（PowerShell），再用ls或dir确认index.js真在当前目录 - 别写
node src/index.js然后指望require('./utils')能找到src/utils.js——require是相对process.cwd()解析的，不是相对文件位置
ES Module 报错 Cannot use import statement 怎么解
这不是 VSCode 的锅，是 Node 默认用 CommonJS 模式解析 .js 文件。遇到 import 就崩，说明模块类型没对齐。
- 方案一：项目根目录
package.json加字段"type": "module"（注意英文引号、无逗号结尾）；加完必须重启 VSCode，否则调试器读不到 - 方案二：把文件后缀改成
.mjs，再运行node index.mjs，Node 会自动识别为 ES Module - 如果用
code-runner插件，它默认不读package.json的type，需手动改code-runner.executorMap："javascript": "node --experimental-specifier-resolution=node $fileName" - 调试时（
launch.json）也依赖这个配置；没声明"type": "module"，断点可能命中，但__dirname会是undefined，require直接报错
调试器断点灰色、程序静默退出？先查 program 路径
launch.json 里 program 字段写错是最隐蔽的失败原因——VSCode 不报错，只是不启动。
- 绝对别写死路径如
"program": "app.js"；正确写法是"program": "${workspaceFolder}/src/app.js"，确保跨平台且指向真实文件 - 新增配置后，先在终端里手动执行一遍
node ${workspaceFolder}/src/app.js，确认能跑通再调试 - 如果用了
nodemon或ts-node，不要在launch.json里直接设program为它们；应配runtimeExecutable，并把入口文件传给args - 断点灰色通常意味着 VSCode 根本没加载到源码映射——检查文件是否被 Webpack/Babel 处理过，或者
sourceMaps是否设为true（仅限编译型场景）
真正容易被忽略的点：VSCode 从不自己运行 JS，它只是帮你调用系统里的 node。哪怕装了十个插件、写了十版 launch.json，只要 which node 在系统终端里没输出，一切运行和调试都是空转。
