Fastify调试断点不触发的根本原因是Node.js的V8 Inspector未启用，必须通过--inspect=0.0.0.0:9229启动并配置VSCode attach模式、正确sourceMaps及outFiles路径，且Schema验证断点需放在preValidation钩子中。
Fastify 调试断点不触发？必须加 --inspect 启动参数
VSCode 断点静默跳过，不是插件问题，也不是代码写错了——根本原因是 Node.js 的 V8 Inspector 没启用。Fastify 本身不带调试能力，它只是个框架，真正执行的是 node 进程。
常见现象：打上断点后程序照常跑完、控制台无报错、VSCode 左下角也没显示“已连接调试器”。本质是 VSCode 根本连不上调试通道。
-
node --inspect=0.0.0.0:9229 src/index.ts是 TypeScript 项目最稳的启动方式（配合ts-node/register/transpile-only） - JS 项目直接用
node --inspect=0.0.0.0:9229 src/index.js，别省略地址写成--inspect（默认绑定localhost，Docker/WSL 下 VSCode 连不上） - 若用
fastify startCLI，必须带-w --inspect=0.0.0.0:9229，否则热重载和调试都失效
launch.json 该用 attach 而不是 launch
Fastify 启动极快，生命周期短，launch 模式容易因时序问题错过断点——尤其你用了 nodemon 或 ts-node-dev 时，VSCode 还没 attach 上，进程已经跑完了。
attach 是主动连已运行的进程，可控性高，适合 Fastify 开发流。关键配置项不能错：
-
port必须和启动命令里的--inspect=:9229完全一致（常见填错为9228或9230） -
sourceMaps: true是开关，但真正起作用的是outFiles——TypeScript 项目必须精准指向编译输出路径，例如"${workspaceFolder}/dist/**/*.js"，不能写成**/*.js - 加
"restart": true可让 VSCode 在进程重启后自动重连（比如保存文件触发nodemon重启）
Schema 验证逻辑里打不了断点？检查 preValidation 生命周期钩子位置
Fastify 的 Schema 不是“自动生效”的魔法，它依赖 preValidation 钩子做校验。如果你在路由 handler 函数里打断点想看验证失败后的 error，大概率会错过——因为错误在进入 handler 前就被拦截并返回了 400。
想调试 Schema 行为，断点得打在钩子函数里，而不是 handler 内部：
- 全局注册：
fastify.addHook('preValidation', (request, reply, done) => { /* 在这里打断点 */ }) - 单路由注册：
fastify.get('/', { schema: { ... } }, async (request, reply) => {...})不会暴露校验过程；需显式加钩子：preValidation: (req, res, done) => { /* 打断点 */ } - 注意：
preValidation钩子中request.body和request.query已解析，但尚未经过 Schema 校验——断点放这里能看到原始输入，也方便加console.log对比预期
TS 项目断点映射失败？tsconfig.json 和 outFiles 必须对齐
断点打在 .ts 文件却停在 .js 上，或直接不触发，90% 是 sourceMap 路径没对上。Fastify 项目常用两种 TS 运行方式，配置差异大：
- 用
ts-node：确保tsconfig.json中"sourceMap": true或"inlineSourceMap": true至少一个开启；launch.json中outFiles可留空或设为["${workspaceFolder}/src/**/*.js"]（ts-node默认不生成独立.js文件） - 用
tsc编译：检查tsconfig.json的"outDir"（如"dist"），然后outFiles必须写成"${workspaceFolder}/dist/**/*.js"；Windows 下路径别用反斜杠，VSCode 不识别 - 务必排除
node_modules："skipFiles": ["<node_internals>/**", "node_modules/**"]</node_internals>，否则断点可能意外停在node_modules/fastify里（2026 年 4 月起 VSCode 默认行为更激进）
最易被忽略的一点：Fastify 的 preHandler 和 preSerialization 钩子内部异步逻辑，如果没 await 或没 return Promise，断点可能在未完成时就跳走——这不是调试器问题，是 JS 执行模型本身决定的。调试前先确认钩子函数签名和返回值是否匹配文档要求。
