如何在 VSCode 中从零起步配置 Node 环境

能跑 node 命令且 VSCode 可断点调试才算真正配好；需在系统终端执行 node -v 和 npm -v 验证，报错说明 PATH 未配置，LTS 安装须勾选 Add to PATH，Windows 路径禁含中文或空格，macOS/Linux 用 nvm 需确保环境变量已加载。

能跑 node 命令，且 VSCode 能断点调试，才算真正配好——其余插件、格式化、TypeScript 都是锦上添花，不是刚需。

验证 node 和 npm 是否真可用（别跳过这步）

很多人卡在这一步，却以为是 VSCode 设置问题。打开系统终端（不是 VSCode 内置终端），执行：

node -vnpm -v

如果报错 'node' 不是内部或外部命令，说明 Node.js 没进系统 PATH。LTS 安装时必须勾选 Add to PATH；若漏了，需手动把 Node.js 安装目录（如 C:Program Filesodejs）加到系统环境变量 Path 里，然后完全退出 VSCode 进程并重启。

• Windows 用户：路径不能含中文或空格（如 D:我的软件odejs），否则 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 环境没配好，不是 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:nodejsnode.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 所在目录。