VSCode调试NestJS GraphQL网关必须用attach模式，因launch模式与网关自带--inspect冲突导致端口冲突或inspector未就绪；需设request为"attach"、port匹配（默认9229）、删runtimeExecutable、加"restart":true，并确保start:debug运行dist/main.js而非ts-node。
VSCode 调试 NestJS GraphQL 网关必须用 attach 模式，不能用 launch
VSCode 断点不命中、调试器连不上、断点变灰色——90% 是因为用了 request: "launch"。NestJS GraphQL 网关（比如基于 @apollo/gateway 或 @nestjs/graphql 的 federated gateway）启动时自带 --inspect，VSCode 若再自己拉起进程，必然端口冲突或 inspector 未就绪。
正确做法是让 VSCode 只监听，不启动：
-
request必须设为"attach" -
port必须和npm run start:debug中指定的端口完全一致（默认9229） - 删掉
runtimeExecutable和runtimeArgs——它们只在launch场景下有效 - 加上
"restart": true，否则网关重启后调试器断连，断点全部失效
package.json 的 start:debug 脚本必须运行编译后代码，不是 ts-node
GraphQL 网关通常依赖模块动态加载（如 loadServicesFromRemoteEndpoint）、Apollo Federation 协议解析、Schema Stitching 等行为，这些在 ts-node 动态执行下无法被 VSCode 调试器正确映射源码。
你的 package.json 中 start:debug 必须明确构建并运行 dist/main.js：
- ✅ 推荐写法：
"start:debug": "nest build && node --inspect-brk=0.0.0.0:9229 dist/main.js" - ⚠️ 注意
=0.0.0.0:9229中的=0.0.0.0不能省，尤其在 macOS 或 Windows 上，否则可能绑定失败 - ❌ 避免写法：
"start:debug": "nest start --debug"——它默认走ts-node，断点必灰 - 运行前务必确认终端输出含
Debugger listening on ws://127.0.0.1:9229/...，没有这行说明脚本没生效
tsconfig.json 和 sourceMap 必须严格对齐 dist 输出路径
GraphQL 网关常含多层嵌套模块（如 gateway/src/services、gateway/dist/resolvers），sourceMap 错一个层级，断点就找不到对应 TS 文件。
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
检查三项硬性匹配：
-
tsconfig.json中必须有"sourceMap": true和"outDir": "dist" -
launch.json中outFiles必须写成["${workspaceFolder}/dist/**/*.js"]——漏掉**就找不到dist/resolvers/QueryResolver.js这类文件 - 验证方式：打开任意
dist/**/*.js，末尾找//# sourceMappingURL=xxx.js.map，确认该.map文件真实存在且可读（不是空文件）
GraphQL 网关调试要避开 start:dev，断点优先设在 resolvers 和 gateway plugins
npm run start:dev 基于 nodemon 或 ts-node-dev，进程反复销毁重建，Node.js 的 --inspect 端口释放后无法稳定复用，VSCode 连不上新进程。
调试阶段必须停用 start:dev，改用 start:debug；断点应落在真正执行 GraphQL 请求逻辑的位置：
- ✅ 有效位置：
resolvers函数内、ApolloServerPlugin生命周期钩子（如serverWillStart）、RemoteGraphQLDataSource的willSendRequest - ❌ 无效位置：
main.ts顶层导入、AppModule构造函数（常在服务启动前就执行完，断点错过时机） - 注意：如果网关启用了
persistedQueries或queryPlan缓存，首次请求可能绕过 resolver，建议先清浏览器缓存或加extensions: { persistedQuery: null }强制走 resolver
调试真正卡住的地方，往往不是语法或逻辑，而是 sourceMap 路径里少了一个 **，或是 --inspect-brk 绑定到了 127.0.0.1 却在 Docker 容器里跑。
