新手友好型VSCode配置Node环境教程

能跑通 node -v，只能说环境搭了一半；断点不生效、require 报错、npm install 成功了模块却找不到——这些问题，十有八九不是代码或插件有问题，而是 VSCode 压根没拿到和终端一致的 PATH，或者调试配置没对齐运行时。

先下个结论：能跑 node -v 只能说明环境装了一半；断点不生效、require 报错、npm install 成功但模块找不到——这些问题 90% 不是代码或插件的问题，而是 VSCode 没拿到和终端一致的 PATH，或者调试配置没对齐运行时。

VSCode 终端里到底认不认 node，得亲自试一遍

别以为安装界面勾选了“Add to PATH”就万事大吉。VSCode 启动时读的是 GUI 进程加载的环境变量，但很多安装方式——尤其是 Windows 上的默认安装、macOS 上用 nvm 但没配 shell 初始化文件——会导致终端能跑 node -v，VSCode 调试器却报 Command "node" not found。

• 先把所有 VSCode 窗口关掉，彻底退出进程。Windows 上到任务管理器确认 Code.exe 已结束；macOS 在 Dock 右键选「退出」。
• 打开系统终端（不是 VSCode 内置终端），运行 where node（Windows）或 which node（macOS/Linux），确认路径合理，比如 C:Program Filesnodejsnode.exe 或 /usr/local/bin/node。
• 重新启动 VSCode，在内置终端（Ctrl+`）里立刻执行 node -v 和 npm -v——这个结果才是 VSCode 实际能调用的。
• 如果失败，Windows 用户检查系统环境变量 Path 是否包含 Node.js 安装目录；macOS/Linux 用户检查 ~/.zshrc 或 ~/.bash_profile 是否有 export PATH=... 并已经 source 过。

launch.json 里的 runtimeExecutable，什么时候必须写？

除非你明确需要绕过系统 PATH 查找逻辑，否则别轻易动这个地方。比如用 nvm 切了版本但 VSCode 没继承、调试 Electron 内置 runtime、或在 WSL/容器中开发。硬编码路径会让团队协作崩掉，也违背 Node.js 版本管理原则。

• 常见错误：为了“统一版本”在 launch.json 里写死 "runtimeExecutable": "/Users/you/.nvm/versions/node/v18.19.1/bin/node"——这会直接卡死其他成员。
• 正确做法：用 nvm use 18 后再从终端启动 VSCode（code .），让 PATH 自然生效。
• VSCode 1.85+ 支持 runtimeVersion 字段，但它只告警不切换，不能替代 nvm use。
• 验证是否生效：在 index.js 里加一行 console.log(process.execPath)，对比调试输出路径和你预期的 node 路径是否一致。

为什么 npm install 成功了，却报 Cannot find module？

这通常不是 Node.js 环境没装好，而是 VSCode 的语言服务没理解你的项目结构。常见于 monorepo、软链接依赖（npm link）、或 package.json 缺少 "type": "module" 导致 CJS/ESM 解析错乱。

• 先在终端运行 npm ls express（把 express 换成你报错的模块名），确认它真实存在且没有标 extraneous。
• 检查 package.json 是否有 "type": "module"；如果有，所有 .js 文件都按 ESM 解析，require() 会直接报错。
• monorepo 场景下，确保 tsconfig.json 或 jsconfig.json 里配置了 "baseUrl" 和 "paths"，否则 VSCode 的跳转和提示会失效。
• node_modules 被放在父目录（比如 lerna 根目录），而当前工作目录是子包——此时 require 会从子包目录向上找，很可能找不到。

Code Runner 这个插件，最该被跑掉的就是它自己

它默认不加载 package.json 的 "type"、不传 --experimental-specifier-resolution=node、不支持 stdin 输入，遇到 ESM、中文路径、交互式脚本基本必翻车。

• 临时验证单文件逻辑可以，但正式开发中建议禁用，改用内置终端手动执行 node index.js。
• 如果非要保留 Code Runner，得改 settings.json 里的 code-runner.executorMap：
  "ja vascript": "node --experimental-specifier-resolution=node $fileName"（macOS/Linux）
  "ja vascript": "node -r utf-8 --experimental-specifier-resolution=node $fileName"（Windows 中文环境）
• 含 process.stdin.on('data', ...) 的脚本，Code Runner 完全不支持输入，必须切到终端手动运行。
• 调试一律用 VSCode 原生调试器（F5），它支持断点、作用域变量监视、调用栈回溯，比一键运行靠谱得多。

真正卡住人的地方，往往不是语法或框架，而是 VSCode 没拿到和终端一致的 PATH，或是你以为在项目根目录，其实只是打开了一个孤立文件。先确认 node -v 和 npm init -y 都能在 VSCode 终端里成功执行，再动其他配置。