能跑 node 命令且 VSCode 能断点调试才算真正搭好；node -v 在系统终端可用但在 VSCode 终端报 command not found，根本原因是 VSCode 未继承 shell 环境变量：macOS/Linux 需通过终端执行 code . 启动或配置 shellArgs 为 ["-l"] 并彻底重启，Windows 需在系统环境变量中添加 Node.js 路径并重启 VSCode，唯一验证方式是在 VSCode 内置终端执行 node -v 和 npm -v 有输出。
能跑 node 命令，且 VSCode 能断点调试，才算真正搭好——其余插件、格式化、TypeScript 都是锦上添花，不是刚需。
node -v 在系统终端能跑，但在 VSCode 终端里报 command not found
这不是 VSCode 故障，而是它没继承 shell 的环境变量。macOS/Linux 用户从 Dock 或 Spotlight 启动 VSCode 时，which node 输出的路径（比如 /opt/homebrew/bin/node）往往不在其 PATH 里；Windows 用户则大概率是安装 Node.js 时漏选了 “Add to PATH”。
- macOS/Linux：改完
~/.zshrc或~/.bash_profile后，必须重启 VSCode，或直接在终端执行code .启动 - Windows：打开“系统属性 → 高级 → 环境变量”，把
C:\Program Files\nodejs\加进“系统变量”的PATH，再重启所有 VSCode 窗口 - 验证方式只有一种：在 VSCode 内置终端（
Ctrl + `）里执行node -v和npm -v；没输出就别往下配launch.json
按 F5 调试提示 Cannot find runtime 'node'
这错误和代码无关，只说明 VSCode 找不到 node 可执行文件。根本原因还是上一步环境没通，不是配置写错了。
-
launch.json里"program": "${file}"是对的，但前提是当前文件已保存（Ctrl+S），否则调试器读不到磁盘上的真实路径 - 别手动写死
"program": "index.js"——它不带路径，VSCode 会从工作区根目录找，容易错位 - 如果项目有固定入口（如
server.js），用"program": "${workspaceFolder}/server.js"更稳妥
用 code-runner 插件运行 JS 却卡死、乱码或报 import 错误
code-runner 默认命令极简：node $fileName，它不处理编码、模块类型、输入流，也不读 package.json，所以容易出问题。
- Windows 中文路径下乱码：在 VSCode 设置中搜
code-runner.executorMap，把javascript对应值改成："node -r utf-8 $fileName" - 报
Cannot use import statement outside a module：先确保项目根目录有package.json且含"type": "module"，再把 executor 改成："node --experimental-specifier-resolution=node $fileName" - 遇到
process.stdin就假死：这是code-runner的固有限制，它不支持交互式输入；换用内置终端手动运行，或直接按F5进入调试模式
想调试 Worker Threads 或 fork 子进程却断点不命中
开多个终端分别跑 node main.js 和 node worker.js ≠ 多线程调试——这只是两个孤立进程，VSCode 不感知彼此。
- 必须在
launch.json中启用："autoAttachChildProcesses": true - Worker 构造函数或
child_process.fork()必须显式传参：execArgv: ['--inspect-brk=9229']，否则子进程不暴露调试端口 - 主进程启动也要带
--inspect-brk，且端口需与子进程一致（或留空让 Node 自动分配，避免冲突） - 若用了
ts-node或esbuild-node启动，autoAttachChildProcesses会失效——它们绕过了标准 Node.js 启动流程
最容易被忽略的是：VSCode 终端是否真的加载了你 shell 里已生效的 npm 配置。比如你在系统终端能用 nodemon，但在 VSCode 里提示 command not found，大概率就是终端没读取 ~/.zshrc，这时重启 VSCode 或手动执行 source ~/.zshrc 更直接。
