node -v 报错说明Node.js未正确安装或环境变量未配置，必须先解决此问题才能进行VSCode调试、npm安装等操作；Windows需勾选Add to PATH或手动添加路径，macOS/Linux需通过nvm正确配置并验证which node。
node -v 报错就别往下走了
VSCode 本身不带 Node.js，node 命令必须在系统终端（非 VSCode 内置终端）里能直接运行，否则后续所有调试、npm 安装、launch.json 配置全都会失效。
常见错误现象：'node' 不是内部或外部命令（Windows）、command not found: node（macOS/Linux）
- Windows 用户：安装 LTS 版时务必勾选 Add to PATH；若漏选，手动把
C:\Program Files\nodejs（或你实际的安装路径）加进系统环境变量Path，然后彻底关闭所有 VSCode 窗口和后台进程再重开 - macOS/Linux 用户用
nvm：确认source ~/.nvm/nvm.sh已写入~/.zshrc或~/.bash_profile，新开终端执行which node应返回类似/Users/xxx/.nvm/versions/node/v20.15.1/bin/node - 路径含中文或空格（如
D:\我的软件\nodejs）会导致npm静默失败——重装到纯英文无空格路径
VSCode 调试器不需要额外插件
VSCode 自带 Node.js 调试支持，Node.js Extension Pack、Debugger for Node.js 这类插件已过时，装了反而可能干扰断点命中或报 Cannot find runtime '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}" 表示运行当前文件。
- 断点设在
console.log行号左侧，按F5启动——成功则控制台输出ok，且调试面板显示变量和调用栈 - 如果卡在启动界面几秒后退出，或提示
Cannot find runtime 'node'，一定是上一步node -v没真正生效，不是配置问题 -
launch.json中的console字段默认为internalConsole，若想看到npm输出（比如npm start日志），需显式加"console": "integratedTerminal"
调试 npm script 和 nodemon 的正确姿势
默认生成的 launch.json 只适合单文件调试。想调试 npm start 或热重载服务，不能简单改 program 字段硬套，否则会失败或无法断点。
调试 npm start：
- 把
"program"改成"npm"，"args"设为["start"] - 必须加
"console": "integratedTerminal"，否则看不到命令行输出 - 确保
package.json中"scripts": { "start": "node index.js" }类定义清晰，避免嵌套调用导致调试器找不到入口
调试 nodemon 热重载：
-
不能在
launch.json里直接跑nodemon index.js——VSCode 调试器不支持进程热替换 - 正确做法：终端先执行
nodemon --inspect-brk index.js（--inspect-brk让它启动即暂停） - 再在
launch.json中配"type": "node"+"request": "attach"+"port": 9229（nodemon默认端口）
第一个服务器别从 http.createServer 开始
新手照抄 const http = require('http') 示例，常因漏写 server.listen()、端口被占、浏览器缓存旧响应而以为“环境没跑起来”，其实只是逻辑不完整。
更稳妥的起步顺序：
- 先写
console.log('Hello from Node.js');，node index.js跑通——确认环境链路没问题 - 再用
express：执行npm init -y && npm install express，然后写最小可运行服务 - 示例代码（
app.js）：const express = require('express');<br>const app = express();<br>app.get('/', (req, res) => res.send('OK'));<br>app.listen(3000, () => console.log('Server running on http://localhost:3000')); - 注意：
app.listen()必须调用，且端口未被其他进程占用（可用lsof -i :3000或netstat -ano | findstr :3000检查）
复杂点在于环境变量加载时机、nodemon 与调试器的协作机制，以及 Windows 下 PATH 刷新延迟——这些地方容易被忽略，但恰恰决定你能不能在 5 分钟内看到第一个 OK。
