VS Code `launch.json` 指南（Node.js版）-Day30

一、launch.json 是什么？

简单说，它就是 VS Code 的**"调试启动器说明书"**。

平时你调试 Node.js 程序，可能是在终端里输入：

node index.js

而 launch.json 就是告诉 VS Code："以后我按 F5 的时候，你就帮我执行这条命令，并且挂上调试器"。

文件位置：

你的项目/
├── .vscode/
│   └── launch.json    ← 在这里
├── index.js
└── package.json

二、Node.js 最常用的 4 种配置

下面这 4 个配置覆盖了 90% 的日常场景，直接复制就能用。

场景 1：调试当前打开的 JS 文件

适合：写了个小脚本，想快速跑一下看看结果。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "运行当前文件",
            "type": "node",
            "request": "launch",
            "program": "${file}"
        }
    ]
}

用法 ：在 VS Code 里打开某个 .js 文件 → 按 F5，就会运行这个文件。

${file} 是个变量，表示"当前打开的文件"。

场景 2：调试 Express / Koa 服务器

适合：后端 API 开发，启动一个 HTTP 服务。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "启动服务器",
            "type": "node",
            "request": "launch",
            "program": "${workspaceFolder}/server.js",
            "env": {
                "NODE_ENV": "development",
                "PORT": "3000"
            },
            "console": "integratedTerminal"
        }
    ]
}

关键字段解释：

字段	作用
program	服务器入口文件路径，${workspaceFolder} 表示项目根目录
env	环境变量，这里设置了开发模式和端口号
console	输出到哪里，integratedTerminal 表示 VS Code 内置终端

场景 3：用 npm 脚本启动（推荐）

适合：项目用 npm start 或 npm run dev 启动，比如 Next.js、NestJS 项目。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "npm run dev",
            "type": "node",
            "request": "launch",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run", "dev"],
            "console": "integratedTerminal"
        }
    ]
}

等价于在终端执行：

npm run dev

只是 VS Code 会自动挂上调试器，你可以在代码里打断点。

场景 4：Attach 到已运行的进程（配合 nodemon）

适合：用 nodemon 启动服务，想在不重启的情况下附加调试。

第一步 ：用带 --inspect 的方式启动程序：

nodemon --inspect index.js
# 或者
node --inspect index.js

终端会输出：

Debugger listening on ws://127.0.0.1:9229

第二步 ：launch.json 配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "附加到进程",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "restart": true
        }
    ]
}

⚠️request不是launch，是attach！！！

"request": "attach", // ← 我不启动新程序，我去连一个已有的

"port": 9229, // ← 连哪个端口？就连上面开的 9229

"restart": true // ← 如果程序重启了，自动重新连

restart: true 的作用 ：当你修改代码后，nodemon 会自动重启服务，调试器也会自动重新连上，不用手动操作。

三、一个"全能版"配置

把上面 4 个场景合并到一个文件里，按 F5 旁边的下拉框切换：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "▶ 运行当前文件",
            "type": "node",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        },
        {
            "name": "🚀 启动服务器",
            "type": "node",
            "request": "launch",
            "program": "${workspaceFolder}/server.js",
            "env": {
                "NODE_ENV": "development"
            },
            "console": "integratedTerminal"
        },
        {
            "name": "📦 npm run dev",
            "type": "node",
            "request": "launch",
            "runtimeExecutable": "npm",
            "runtimeArgs": ["run", "dev"],
            "console": "integratedTerminal"
        },
        {
            "name": "🔗 附加到 nodemon",
            "type": "node",
            "request": "attach",
            "port": 9229,
            "restart": true
        }
    ]
}

四、常见问题

1. 断点打上去是灰色的，不生效

原因：你运行的是编译后的代码（比如 TypeScript 转成的 JS），但断点打在源文件上。

解决 ：需要配置 sourceMap，或者直接用 ts-node 调试：

{
    "name": "调试 TypeScript",
    "type": "node",
    "request": "launch",
    "runtimeExecutable": "npx",
    "runtimeArgs": ["ts-node", "${file}"],
    "console": "integratedTerminal"
}

2. 环境变量没生效

检查优先级：launch.json 里的 env 会覆盖系统环境变量。如果你同时用了 .env 文件，建议装 dotenv 扩展，或者在 runtimeArgs 里加载。

3. 按 F5 没反应

检查 VS Code 左下角是否显示了正确的调试配置名称。如果没有 launch.json，VS Code 会尝试自动推断，但不一定准。

4. 怎么传命令行参数？

"args": ["--port", "3000", "--verbose"]

这等价于：

node server.js --port 3000 --verbose

五、快速上手步骤

1. 打开你的 Node.js 项目
2. 按 Ctrl+Shift+D（或点击左侧调试图标）
3. 点击"创建 launch.json 文件" → 选择 Node.js
4. VS Code 会自动生成基础配置
5. 根据上面的模板修改，保存
6. 按 F5 开始调试

六、调试快捷键

按键	作用
F5	启动 / 继续运行
Shift + F5	停止
F9	在当前行打断点
F10	单步跳过（不进入函数内部）
F11	单步进入（进入函数内部）

总结 ：launch.json 就是告诉 VS Code "按 F5 时怎么启动我的 Node 程序" 。最常用就 4 种模式------运行当前文件、启动服务器、执行 npm 脚本、附加到已有进程。配好一次，团队所有人都能直接用。