VSCode 不运行 Node.js 服务器，仅提供编辑、启动和调试能力；真正执行的是本地 node，调试依赖内置 Node.js 调试器。需确保 node/npm 正确安装并可用，launch.json 配置准确（尤其 program、cwd、runtimeExecutable），TypeScript 需 sourceMap 和 ts-node 配合，ESM 和 nodemon 需特殊配置，断点失效多因路径、版本或源码映射问题。
VSCode 本身不“搭建” Node.js 服务器，它只是提供编辑、启动和调试能力；真正运行服务器的是你本地安装的 node，而调试依赖 VSCode 内置的 Node.js 调试器（基于 Chrome DevTools Protocol）。只要 node 可执行、项目结构清晰、launch.json 配置正确，调试就能跑起来——不是靠插件堆砌，而是靠路径和参数对得上。
确认 node 和 npm 已正确安装并可用
这是所有后续操作的前提。VSCode 不会帮你装 Node.js，也不会自动识别错位的 PATH。
- 在终端运行
node -v和npm -v，必须返回版本号（如v20.11.1），不能报command not found - 如果用 nvm / fnm 管理多版本，确保当前 shell 中
node指向你期望的版本（which node查路径） - VSCode 的集成终端可能继承自不同 shell（如 zsh vs bash），重启 VSCode 或从命令行用
code .启动可避免环境不一致
用 launch.json 配置调试入口（关键且易错）
.vscode/launch.json 是 VSCode 调试行为的唯一权威配置。写错路径、忽略 cwd 或混用 program 与 runtimeExecutable 是最常见失败原因。
- 不要直接复制网上“通用模板”，重点看
program是否指向你的实际入口文件（如./src/server.js或./index.js） - 如果项目用
ts-node或esbuild-node，必须设runtimeExecutable并传参，例如：{ "type": "node", "request": "launch", "name": "Launch with ts-node", "runtimeExecutable": "npx", "runtimeArgs": ["ts-node", "--project", "./tsconfig.json"], "args": ["./src/server.ts"], "cwd": "${workspaceFolder}" } -
cwd（工作目录）影响require()解析、配置文件读取（如.env）、静态资源路径——务必设为"${workspaceFolder}"或明确路径，别留空
断点不生效？检查源码映射和运行模式
尤其在 TypeScript、ESM、或使用 nodemon 的场景下，断点失效几乎都源于调试器看不到原始代码位置。
- TypeScript：确保
tsconfig.json含"sourceMap": true，且编译输出（outDir）与调试program路径匹配；若直接调试.ts文件，需用ts-node配置（见上条） - ESM 项目（含
"type": "module"）：VSCode 1.85+ 原生支持，但旧版需加"runtimeArgs": ["--loader", "ts-node/esm"]（配合ts-node） - 用
nodemon自动重启？不要在launch.json里调nodemon—— 改用attach模式：先命令行启动nodemon --inspect-brk server.js，再配一个attach类型的配置连localhost:9229
调试时修改代码不热更新？这不是调试器该管的事
VSCode 的 Node.js 调试器只负责暂停、单步、变量查看；热重载（HMR）或文件变更重启是 nodemon、ts-node-dev 或框架自身（如 Next.js）的能力。
- 想边调试边改代码立即生效？单独开一个终端运行
nodemon --watch src --exec node --inspect-brk server.js，然后用attach模式连接 - Express/Fastify 等纯 HTTP 服务没有 HMR，所谓“热更新”本质是进程重启——注意调试器断连后要手动点 “Restart” 按钮，或配
restart: true（仅限 launch 模式） - 某些 ORM（如 Prisma）生成的客户端代码带 source map，但调试时跳转可能指向生成文件而非你的模型定义，这时断点要打在调用层，而非
prisma.user.findMany()内部
真正卡住的往往不是配置语法，而是 cwd 和 program 的路径解析、Node.js 版本对 ESM 的支持粒度、以及你以为在调试 TypeScript 实际却在跑编译后的 JS——这些细节不会报错，只会让断点静默失效。
