必须安装GraphQL for VSCode插件并正确配置schemaPath，确保右下角显示“GraphQL: connected”；需手动设置文件语言模式、校准gql标签名，通过Output面板的GraphQL日志排查路径、语法或schema加载失败问题。
装错插件或没连上 Schema，VSCode 就只是个高亮编辑器，补全、跳转、校验全失效——不是功能没做，是你没配对。
必须装 GraphQL for VSCode，别碰其他“GraphQL”名字的插件
VS Code 市场里叫 “GraphQL” 的插件不止一个，但真正能联动 Schema 实现字段补全的，只有 GraphQL for VSCode（作者：Prisma）。GraphQL Language Service 和已归档的 GraphQL Tools 插件不维护了，装了也白装。装完后打开任意 .graphql 文件或含 gql 模板字面量的 .ts/.js 文件，右下角状态栏必须显示 GraphQL: connected；不显示就说明没连上，重启 VSCode 才生效，重载窗口不够。
graphql.config.yml/js 里 schemaPath 必须指向合法本地文件
远程 endpoint（如 http://localhost:4000/graphql）容易因 CORS、鉴权或 introspection 关闭失败，本地 .graphql 文件才是联调稳定性的底线。配置时注意：
-
schemaPath是相对于graphql.config.yml所在目录，不是工作区根目录 - Windows 用户禁用反斜杠：
schemaPath: "schema\schema.graphql"会解析失败，得写成schemaPath: "schema/schema.graphql" - 支持数组写法，多个 Schema 文件要显式列出：
schemaPath: ["schema/types.graphql", "schema/queries.graphql"] - 路径不能带
./前缀——YAML 解析器会忽略它，./schema.graphql等价于schema.graphql
文件语言模式和 gql 标签名必须手动对齐
VSCode 不会自动把 .gql 或 .graphql 文件识别为 GraphQL 语言，即使插件已装。必须手动设置：
- 打开任意
.graphql文件 → 右下角点语言标识（如 “Plain Text”）→ 选 “GraphQL” - 或在
settings.json中加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"} - 若在 JS/TS 里用模板字面量，插件默认只认
gql标签；用了graphql或query，得配："graphql.taggedTemplateLiteralName": ["gql", "graphql"] -
gql模板必须单独成行、前后无拼接：const q = gql`...`可以，const q = gql`` + ''或嵌在对象属性里会直接让插件失焦
补全失效？先看 Output 面板里的 GraphQL 日志
插件后台 Language Server 出错时，VSCode 界面零提示，只会表现为“没补全”“跳转灰掉”。必须打开 Output 面板（Ctrl+Shift+U），下拉选 GraphQL。常见错误信息包括：
-
Unable to load schema from ...：路径错、文件不存在、或内容不是合法 SDL（比如误用了 introspection JSON） -
Failed to parse document：查询语法不标准，比如 query 名含空格、fragment 未定义或未引入 -
No schema available：config 文件存在但schemaPath字段缺失或拼写错误（注意是schema，不是schemaPath在 js 版 config 里）
Schema 文件一旦更新，必须手动重新加载（重启 VSCode 或执行 Developer: Reload Window），插件不会监听文件变化自动刷新。
