必须安装GraphQL for VSCode（Prisma Labs出品），卸载Apollo等废弃插件，彻底重启VSCode，正确配置graphql.config.yml中schema路径（相对该文件位置、用正斜杠、多文件用数组），绑定.graphql/.gql语言模式，并确保Output面板出现“Loaded schema from”日志。
GraphQL for VSCode 插件必须装对，否则补全和跳转全失效
VS Code 市场搜 “GraphQL”，出来的插件里只有 GraphQL for VSCode（Prisma Labs 维护）能加载 schema、支持字段补全、Ctrl+Click 跳转 resolver。其他同名插件如 GraphQL Language Service 已废弃，Apollo GraphQL 专注 client 代码生成，装了反而让状态栏卡在 GraphQL: disconnected，Output 面板反复报 Unable to load schema from ./schema.graphql。
装完必须彻底关闭所有 VSCode 窗口再重开——Developer: Reload Window 不触发 Language Server 启动，右下角不会显示 GraphQL: connected。
- 打开任意
.graphql文件，右下角语言模式必须是GraphQL，不是Plain Text - 若不对，手动在
settings.json加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"} - 改完仍不生效？检查是否禁用了所有其他 GraphQL 相关插件
graphql.config.yml 路径写错，schema 就永远加载不上
插件靠 graphql.config.yml 定位 schema，但路径解析规则反直觉：它是相对于该配置文件所在目录，不是项目根目录，也不是当前编辑的文件位置。
常见错误：
-
schema: src/schema.graphql—— 错，除非graphql.config.yml也在src/里 -
schema: schema\schema.graphql（Windows）—— 错，YAML 不认反斜杠，必须写schema: schema/schema.graphql - 多文件 schema 写成字符串：
schema: "schema/types.graphql"—— 错，必须用数组：schema: ["schema/types.graphql", "schema/resolvers.graphql"] - 远程 endpoint：
schema: http://localhost:4000/graphql—— 容易静默失败（CORS、introspection 关闭、服务未启），调试阶段优先用本地.graphql文件
断点打在 resolver 里不命中？先确认 Node 调试器连上了
resolver 是普通 JS 函数，断点逻辑和任何 Node.js 代码一致，但前提是调试器已 attach 到进程。常见现象：断点灰掉、F5 没反应、控制台无输出。
两种典型场景对应不同 launch.json 配置：
- 直接运行入口文件（如
node server.js）："type": "node"+"request": "launch"+"program": "${workspaceFolder}/server.js" - 用
nodemon或ts-node启的服务："type": "node"+"request": "attach"+"port": 9229，且启动命令必须含--inspect=9229 -
runtimeExecutable别写node_modules/.bin/ts-node这种相对路径，优先留空或填绝对路径
schema 文件本身格式不对，校验就必然失败
插件只认合法 SDL 格式（Schema Definition Language），即纯文本、带 type Query { ... } 结构的 .graphql 文件。不能直接拿 introspection JSON 当 schema 用。
生成方式推荐：
- 用
curl 'http://localhost:4000/graphql?query={__schema{types{name}}}' | jq -r '.data.__schema.types[] | select(.name | startswith("Query") or startswith("Mutation"))' > schema.graphql提取核心类型（需配合jq） - 或用脚本调
graphql-introspection导出标准 SDL - Keystone/Nexus/Apollo Server 启动后，用
npm run graphql:download自动拉取并覆盖schema.graphql - 文件为空、语法错误（如漏掉
}）、BOM 字符都会导致Loaded schema from日志不出现
最常被忽略的点：schema 加载成功与否，唯一可靠判断是 Output 面板里 GraphQL 日志是否出现 Loaded schema from。没这行，所有补全、跳转、校验都只是表面正常而已。
