怎么在 VSCode 中配置 Launch.json 调试 Node.js 应用？

在 VSCode 中调试 Node.js 应用，最推荐的方式是在项目根目录创建 `.vscode/launch.json` 文件并选择"Node.js: Launch Program"配置。此方法适用于本地开发场景，风险边界在于需确保入口文件路径正确且未被其他进程占用端口。

先说结论：通过 VSCode 内置调试器配置 launch.json 是本地调试 Node.js 的标准方案，无需额外插件即可实现断点调试。

适合：本地开发环境、需要断点检查变量、排查异步逻辑错误的场景。
先准备：确认 Node.js 已安装、项目入口文件路径明确、VSCode 已打开项目文件夹。
验收：点击启动后能进入断点、控制台输出正常、变量监视面板可读取数据。

快速处理思路

如果不熟悉手动编写配置，可直接使用 VSCode 的自动生成向导。在调试视图中点击"创建 launch.json 文件"，选择"Node.js"环境，系统会自动生成基础配置模板。

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "启动程序",
      "skipFiles": [
        "<node_internals>/**"
      ],
      "program": "${workspaceFolder}/app.js"
    }
  ]
}

将上述代码中的 `program` 字段修改为实际入口文件路径，保存后即可按 F5 启动调试。

为什么会这样

VSCode 调试 Node.js 依赖于调试适配器协议（Debug Adapter Protocol），需要明确知道进程启动方式。

配置 launch.json 的本质是告诉 VSCode 如何启动 Node 进程以及传递哪些参数。`type: node` 表示使用 Node 调试器，`request: launch` 表示由 VSCode 启动进程，而 `program` 指定了脚本入口。如果路径错误或环境不匹配，调试器无法附加到进程，导致启动失败。

分步处理

按以下步骤完成配置，每步完成后检查对应状态。

步骤 1：打开调试视图

点击 VSCode 左侧活动栏的"运行和调试"图标（快捷键 Ctrl+Shift+D）。如果尚未初始化，点击"创建 launch.json 文件"链接。

步骤 2：选择环境

怎么在 VSCode 中配置 Launch.json 调试 Node.js 应用？

在弹出的选择框中找到并点击"Node.js"。系统会在 `.vscode` 文件夹下生成 `launch.json` 文件。

步骤 3：修正入口路径

找到 `program` 字段，将默认值修改为项目实际入口文件。例如入口是 `src/index.ts`，则填写 `${workspaceFolder}/src/index.ts`。如果使用 TypeScript，需确保已配置 `preLaunchTask` 进行编译。

步骤 4：启动调试

点击绿色启动按钮或按 F5。观察下方调试控制台是否有报错，代码编辑器左侧边栏是否显示红点断点。

怎么验证是否生效

通过断点命中和变量监视确认调试会话正常。

检查点 1：断点暂停

在代码逻辑行号左侧点击添加红点断点。启动调试后，程序执行到该行应自动暂停，顶部调试工具栏显示继续、步过、步入按钮。

检查点 2：变量读取

在暂停状态下，将鼠标悬停在变量上，应显示当前值。同时在"运行和调试"侧边栏的"变量"面板中能看到作用域内的所有变量。

检查点 3：控制台输出

查看"调试控制台"面板，确认 `console.log` 输出正常，且没有报错信息如 `Cannot find module` 或 `EADDRINUSE`。

常见坑

配置过程中容易遇到路径和环境问题，需注意以下边界。

路径相对性错误

`program` 字段建议使用 `${workspaceFolder}` 变量而非硬编码绝对路径，否则更换电脑或协作时配置会失效。

Attach 与 Launch 混淆

`launch` 用于 VSCode 启动进程，`attach` 用于附加到已运行的进程。如果手动在终端运行了 `node app.js`，则需使用 `attach` 配置并指定端口，否则会导致端口冲突或无法断点。

TypeScript 未编译

直接调试 TS 文件需配置 `preLaunchTask` 调用 tsc 编译，或安装 `ts-node` 并在 `runtimeExecutable` 中指定。否则调试器会报找不到 JS 文件或 sourcemap 错误。

常见问题

Launch 和 Attach 配置有什么区别？

Launch 由 VSCode 启动 Node 进程，Attach 是附加到已存在的 Node 进程。

本地开发通常用 Launch，方便管理生命周期；如果需要调试已启动的服务或 Docker 容器内的进程，则必须用 Attach 模式并开启 inspect 端口。

如何调试 TypeScript 项目？

需要配置 sourceMap 并在 launch.json 中指向 TS 文件。

确保 `tsconfig.json` 中开启 `sourceMap: true`，并在 launch.json 的 `program` 指向入口 TS 文件，VSCode 会自动通过 sourcemap 映射到源代码。

调试时控制台中文乱码怎么办？

通常是终端编码设置问题，与 launch.json 无关。

尝试在 VSCode 设置中搜索 `terminal.integrated.defaultProfile` 调整默认 Shell，或在 launch.json 的 `env` 字段设置 `NODE_OPTIONS=`--no-deprecation`` 等环境变量排查干扰。

参考来源

Visual Studio Code Documentation, "Node.js Debugging in Visual Studio Code", https://code.visualstudio.com/docs/nodejs/nodejs-debugging