VSCode从零配置Node环境完整教程

能够成功运行 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 所在的目录。