如何在vscode中设置与调试Node.js应用程序？【教程】

VS Code 调试 node.js 需正确配置 launch.json，否则断点不生效、console.log 无输出、process.env 读不到环境变量；须确认 node 全局可用且 ≥14，显式设置 runtimeExecutable、env 和 console，并注意 express/TS 的特殊配置要求。

VS Code 调试 Node.js 不需要额外装插件，但必须正确配置 launch.json，否则断点不生效、console.log 看不到输出、process.env 读不到环境变量——这些是新手最常卡住的三个点。

确认 node.js 已全局可用且版本 ≥ 14

VS Code 的调试器依赖系统 PATH 中的 node 命令。如果终端里能运行 node -v，但 VS Code 启动调试时报 “command ‘node‘ not found”，大概率是 VS Code 没继承 shell 的环境（尤其在 macOS 或 linux 下用 zsh 启动时）。

• 在终端中执行 which node，复制路径（如 /opt/homebrew/bin/node）
• 打开 VS Code 设置（Cmd+, / Ctrl+, ），搜索 debug.node.autoAttach，确保为 on（方便直接 F5 启动）
• 若仍失败，在 .vscode/settings.json 中显式指定：

  "terminal.integrated.defaultProfile.osx": "zsh",
  "terminal.integrated.env.osx": { "PATH": "/opt/homebrew/bin:${env:PATH}" }

生成正确的 launch.json 配置

别手写 launch.json —— VS Code 提供的自动引导容易漏掉关键字段。点击「运行」→「打开启动配置」→ 选 Node.js，它会生成基础模板，但以下三项必须手动补全：

• runtimeExecutable：指向你实际使用的 node（尤其当你用 nvm 切换版本时），例如：

  "runtimeExecutable": "/Users/you/.nvm/versions/node/v18.18.2/bin/node"

• env：环境变量不能靠 .env 文件自动加载，必须显式写进配置，比如：

  "env": { "NODE_ENV": "development", "PORT": "3001" }

• console：默认 integratedTerminal 可能吞掉某些日志，改成 externalTerminal 更可靠（macOS 下会弹出 Terminal.app）

调试 Express/Koa 等 Web 应用时的断点陷阱

Express 启动后代码才执行，但 VS Code 默认在入口文件第一行就暂停（program 模式）。如果你在路由处理函数里打断点却从不触发，问题往往出在启动方式上：

• 不要用 nodemon 直接替换 node —— 它是子进程，调试器抓不到。改用 nodemon --inspect + VS Code 的 attach 模式
• 推荐用 run 模式配合 --inspect-brk 参数：

  "configurations": [{
    "type": "node",
    "request": "launch",
    "name": "Launch Express",
    "program": "${workspaceFolder}/app.js",
    "args": ["--inspect-brk"],
    "skipFiles": [""]
  }]

• skipFiles 必须加，否则断点会停在 internal/modules/cjs/loader.js 这类内部文件里

调试 typescript 项目要多走两步

TS 编译后的 JS 才是 Node 执行的，所以源码映射（source map）必须存在且被识别。光有 tsconfig.json 里的 "sourceMap": true 不够：

• 确保 tsc 已运行过（或开启 watch），输出目录（如 dist/）下有 .js.map 文件
• launch.json 中的 program 必须指向编译后的 JS 入口（如 dist/index.js），不是 src/index.ts
• 加 outFiles 字段帮助定位：

  "outFiles": ["${workspaceFolder}/dist/**/*.js"]

• 如果用 ts-node 直接跑 TS，调试需用 node 类型 + runtimeArgs：

  "runtimeArgs": ["-r", "ts-node/register"],
  "args": ["${workspaceFolder}/src/index.ts"]

真正卡住人的从来不是“怎么配”，而是“为什么配了还不生效”——多数时候是 runtimeExecutable 指向了旧版本 Node，或 env 漏写了某个关键变量，又或者 outFiles 路径没匹配到生成的 map 文件。盯住调试控制台左下角的「已连接」状态和右上角的「断点验证」图标，比反复重启更省时间。