VSCode 的调试功能用过就回不去，但一旦出问题，能把人逼疯。断点打了不命中、控制台空跑、attach 半天连不上——这些问题我全踩过。这篇不讲教科书，就讲实际干活中遇到怎么解决。

一、先搞清楚现状：你遇到的是哪种"不生效"？

调试不生效是个笼统的说法，诱因不同解法完全不同。先对号入座：

以上四种是最常见的，对应不同的根因：一个一个来。

二、从源头搞懂 launch.json

VSCode 调试的核心就靠 launch.json。很多人配置乱抄，要么 launch 和 attach 混用，要么漏了关键字段，导致调试器根本不知道该干嘛。先搞清楚两个最基础的概念：

2.1 launch vs attach：这是两条完全不同的路

2.2 launch.json 字段详解（YAML 格式）

现在来看一个完整的 launch.json，理解每个字段干什么。VSCode 支持在 .vscode/launch.json 里直接写 YAML，简洁好读：

逐个解释关键字段：

• runtimeExecutable：用什么程序跑。默认是 node，但如果你用 ts-node、tsx、nodemon，就换成对应的命令
• runtimeArgs：传给运行时进程的参数。--nolazy 关闭 V8 惰性编译，确保代码在第一行就能断住；--inspect-brk=9229 开启调试端口并在第一行停住
• program：入口文件路径，注意是绝对路径或 workspaceFolder 为基准
• console：输出走哪里。integratedTerminal 用 VSCode 内置终端，externalTerminal 用系统终端窗口
• restart：调试结束后自动重启，配合 nodemon 实现热更新调试
• skipFiles：这些文件里的代码直接跳过，不进入断点，通常用于过滤 node_modules 和 Node.js 内部模块
• port（attach 专用）：去连哪个端口的调试器

三、断点技巧：打出 debug 效率的最大化

只会打普通断点？那你只发挥了调试器 30% 的能力。以下技巧让调试效率直接翻倍。

3.1 条件断点：只在你关心的条件下停下来

右键点击行号 → 选择"添加条件断点"，或者在已有断点上右键 →"编辑断点"。支持两种表达式：

• 表达式条件：user.id === 42 && status === 'active' — 当条件为 true 时断住
• 命中计数：hitCount >= 5 — 这个位置被命中第 5 次时才停，常用于循环里找特定那次

实战场景：接口被并发调用 50 次，其中某一次数据异常，你想定位是哪次——打普通断点要按 49 次继续，太折磨了。改成 hitCount >= 1 然后配合变量判断：

3.2 函数断点：不知道在哪行但知道函数名

按 Ctrl+Shift+F10（macOS: Cmd+Shift+F10），输入函数名，VSCode 会在所有同名函数的入口处下一个断点。这比搜代码再点行号快得多。

3.3 日志点（Logpoint）：不打断点，只打印日志

右键行号 → "添加日志点"。程序跑到这里不会停，但会在控制台输出一段你定义的消息。完美替代 console.log，还不用改代码。格式：

花括号里写变量名，调试器会实时替换。查循环里变量怎么变的，或者想知道某个函数被谁调了，用这个，比断点安静 10 倍。

3.4 检查（Watch）面板：实时监控变量值

调试时 VSCode 左侧有个 Watch 面板，可以添加表达式。右键选"添加到监视"，或者直接点 + 号输入表达式，比如 user.posts.filter(p => p.liked)，每次断住都会实时显示结果，不用在变量面板里翻层级。

四、Node.js Debug 模式：挑对启动方式

4.1 --inspect vs --inspect-brk：两兄弟别搞混

新手常犯的错误：用 --inspect 然后抱怨"为什么断点没停住程序就结束了"。因为你程序跑完了才想起来开 VSCode attach。解决方法：

• 从头开始调 → 用 --inspect-brk
• 程序已经在跑 → 用 --inspect 然后 attach

4.2 Nodemon 配合调试：热更新也要能断点

用 nodemon 跑项目改代码不用重启，但调试怎么断？两种方式：

方式一：nodemon 直接加 --inspect

然后在 VSCode 里用 "Attach to Node" 配置连到 9229 端口。

方式二：nodemon.json 配置

配合前面 launch.json 里的 "Nodemon 热更新调试" 配置，修改代码后 nodemon 自动重启，VSCode 调试器会重新 attach，调试体验和无热更新的基本一致。

五、Chrome DevTools + VSCode 联合调试

前端项目（React/Vue/Angular）在 Chrome 里跑，VSCode 想断，两者要协调好调试端口，否则会互相抢。

5.1 原理：两者用的是同一个 CDP 协议

Chrome 打开 --remote-debugging-port=9222 后，VSCode 可以通过这个端口接管 Chrome 的调试。关键在于不要让 Chrome 自己开启独立的调试端口，要让两者用同一个。

5.2 正确流程

1. 启动你的前端项目（Vite/Webpack dev server）
2. 用 Chrome 打开 chrome --remote-debugging-port=9222 访问 localhost:3000
3. VSCode launch.json 配置 "request": "attach" + "port": 9222（注意不是 9229）
4. 按 F5，VSCode 会列出 Chrome 里所有可调试页面，选中你的标签页

5.3 sourceMaps 导致断点错位

前端项目通常用 Webpack/Vite 打包，代码是编译后的。如果断点打在编译后代码上，位置会错乱。需要开启 sourceMaps：

pathMapping 是关键——告诉 VSCode Chrome 里的 /src 路径对应本地哪个目录，这样断点就能精确映射到源文件而不是打包后的文件。

六、常见问题排查清单

Q1：断点变空心圆，不生效

• 检查 skipFiles 是否误把目标文件过滤了
• 确认代码被正确 source map 了，编译后的代码行号可能对不上
• 可能是代码被压缩了，开启 source map 或用非压缩 build
• 检查是否有多实例运行，旧进程还在占着调试端口

Q2：F5 按下去程序直接跑完，断点根本拦不住

• 确认用的是 --inspect-brk 而不是 --inspect
• 检查 launch.json 里的 program 路径是否正确
• 确认 runtimeExecutable 指向正确的 node 路径（有些项目用 nvm 指定了版本）

Q3：attach 连上了但断点显示"未经验证"

• 这是 Source Map 映射失败的表现，检查 sourceMaps: true 是否配置
• 检查 webRoot（Chrome 调试）或 cwd（Node 调试）是否正确
• 试着在目标文件第一行手动打个断点，看能否命中；如果第一行能断住说明路径没问题

Q4：nodemon 重启后 VSCode 断不住

• 确保 launch.json 里 "restart": true
• nodemon 重启时调试端口要保持一致，不要每次生成随机端口
• 如果还不行，手动在 nodemon 重启后重新 attach 一次

Q5：ts-node / tsx 跑不起来调试

• 用 node --inspect-brk -r ts-node/register src/app.ts
• 或者用 tsx watch --inspect-brk src/app.ts
• VSCode launch.json 里把 runtimeExecutable 换成 "tsx"

Q6：VSCode 和 Chrome 同时想调试一个标签页

Chrome 和 VSCode 不能同时 attach 同一个 CDP 端口。先在 VSCode 调试，调试完在 VSCode 停止调试（不是关闭 Chrome），Chrome 窗口就恢复自由了。反过来也一样，先关 VSCode 的 attach，Chrome 才能完全接管。

七、调试配置的工程化实践

多人协作项目里，launch.json 建议写入 .vscode/ 并加入 .gitignore，或者在 launch.json 里加清晰注释方便队友。几个推荐实践：

• 环境区分：runtimeArgs 里可以通过 "env" 注入 NODE_ENV，dev 和 production 调试配置分开
• TypeScript 支持：runtimeArgs 加 -r ts-node/register，配合 "outFiles" 指定 source map 位置
• 调试启动脚本：如果项目有 npm run dev:debug 脚本，直接把 runtimeExecutable 指向 npm，runtimeArgs 填 ["run", "dev:debug"]
• Compound 配置：launch.json 支持同时启动多个配置（compound），比如 Node.js 后端 + Chrome 前端同时断住：
  compounds: - name: "全栈调试" configurations: - "Node.js: 启动调试" - "Chrome: 联合调试（前端）"

总结

VSCode 调试不生效，90% 的问题出在 launch.json 配置不对：launch 和 attach 混用、端口没开、路径写错、source map 没配。剩下的 10% 是调试端口被占用或者 skipFiles 误过滤。

搞定这些配置后，VSCode 调试的体验比 console.log 强太多——变量实时查看、条件断点、日志点、call stack 想看哪层看哪层。Chrome DevTools 联合调试在前端项目里也是神器，配合好两者，调试效率直接提升一个档次。

如果这篇帮你解决了问题，或者你还有别的调试坑想聊——