如何在VSCode中配置Node环境调试基于Fastify的后台RESTful接口

VSCode 里调试 Fastify 项目，最让人头疼的往往不是代码逻辑本身，而是你明明打了断点，程序却像没看见一样照跑不误。绿色圆点老老实实亮着，控制台也不报错，可就是不停。这种“静默失效”的根源其实很简单：V8 Inspector 根本没被激活。换句话说，调试通道压根没建立起来，VSCode 根本没连上你那个 Node.js 进程。

那怎么解决？核心就是显式地加一句 --inspect=0.0.0.0:9229 启动参数，然后配合 VSCode 的 attach 模式，把端口、sourceMap 和 outFiles 路径都一一对上。下面咱们把几个关键环节拆开来说。

为什么断点不触发？

Fastify 本身不负责调试，它只是个 Web 框架。Node.js 的 --inspect 参数必须由你手动加到启动命令里。常见的一种情况是：你在终端里只写了 node src/index.ts，然后指望 VSCode 自动识别——不可能的。只有 node --inspect=0.0.0.0:9229 src/index.ts 这种形式才会真正打开调试端口。

这里有几个容易踩的坑：

• 如果只写 --inspect 不加 IP，Node 默认绑定 localhost。在 WSL 或 Docker 环境下，VSCode 从宿主机连不上这个地址，断点自然失效。
• 用 fastify start CLI 的时候，记得同时加上 -w（watch）和 --inspect=0.0.0.0:9229，否则热重载一次，调试端口就关一次，断点就没了。
• TypeScript 项目里用 ts-node 启动时，要加 -r ts-node/register/transpile-only，否则源码映射会失败，断点打在 .ts 文件上却跳到 .js 里，甚至直接跳过。

launch 还是 attach？

对于 Fastify 这种快速启动、而且可能 fork 子进程的框架，request: "attach" 是更稳妥的选择。launch 模式容易因为启动时序或环境变量差异错过断点，尤其配合 nodemon 或 ts-node-dev 时，更是问题频发。

具体操作步骤：

• 在终端里先执行：node --inspect-brk=0.0.0.0:9229 -r ts-node/register/transpile-only src/index.ts（加上 --inspect-brk 可以让程序在第一行代码处暂停，方便你从头开始调试）。
• 然后在 launch.json 里配置："type": "node"、"request": "attach"、"port": 9229，端口必须和启动命令一致。
• 加上 "restart": true，这样进程重启后 VSCode 会自动重连，非常适合热重载场景。
• 地址写 "localhost" 就够了，不需要改成 127.0.0.1 或 0.0.0.0——这是 VSCode 连接本机的地址，不是 Node 绑定的地址。

sourceMap 映射总失败？检查这三个地方

断点明明打在 .ts 文件里，却停在 .js 上，或者直接跳过不执行，十有八九是 sourceMap 路径没对上。Fastify 项目常用的编译路径有两种，对应的配置方式也不同。

• 如果用 tsc 预先编译：确认 tsconfig.json 中 "outDir": "./dist"，然后在 launch.json 里加 "outFiles": ["${workspaceFolder}/dist/**/*.js"]。
• 如果用 ts-node 直接运行：确保 tsconfig.json 包含 "sourceMap": true 或 "inlineSourceMap": true，而且没有被 ts-node 的 transpile-only 模式覆盖掉。
• Windows 路径千万别用反斜杠："outFiles": ["${workspaceFolder}dist***.js"] 这种写法会被 VSCode 忽略，一定用正斜杠。

最后还有一个容易被忽略的细节：--inspect 参数必须出现在启动命令的最前面，而且不能被 npm script 包裹层吞掉。比如你用 npm run dev 启动，但 package.json 里的 dev 脚本如果没把 --inspect 透传过去，VSCode 就连不到任何东西——这比配置写错还难排查，往往是卡住调试的最终原因。