WebStorm需手动安装JetBrains官方GraphQL插件并重启才能启用gql标签高亮与补全；须正确配置graphql.config.json的schema路径、endpoints及includes，否则提示、跳转、执行均失效。
GraphQL 插件没装上，gql 标签根本不会高亮
WebStorm 默认不带 GraphQL 支持，必须手动装插件。很多人以为装了 Node.js 插件就完事了，其实不是——GraphQL 是独立插件，且必须从 JetBrains Marketplace 安装，IDE 内置插件库搜不到。
- 打开
Settings | Plugins（macOS 是Cmd+, → Plugins），切到 Marketplace 标签页 - 搜
GraphQL，认准作者是JetBrains的那个（图标是紫色的 GraphQL 字样） - 点 Install，重启 WebStorm —— 不重启，
gql和graphql模板字符串依然被当普通字符串处理 - 如果项目用的是 Apollo，顺手把
Apollo GraphQL插件也勾上，它能自动识别gql标签并启用字段补全
常见错误现象：gql`{ user { id } }` 里 user 字段没提示、按 Ctrl+Click 跳不到 schema 定义、类型报错不显示。基本就是插件没生效。
graphql.config.json 配置错一个字段，整个 schema 就加载失败
WebStorm 依赖这个配置文件定位 schema，但它对 JSON 结构很敏感。尤其容易栽在 schema 字段写法和 endpoint 权限上。
- 最简可用配置：用本地
.graphql文件时，写成"schema": "./src/schema.graphql"；用远程 API 时，必须用"schema": ["http://localhost:4000/graphql"]（注意是数组！不是字符串） - 如果 API 需要鉴权（比如 AWS Amplify 或带 JWT 的服务），
headers必须写在endpoints下，而不是schema.request.options.headers—— 后者只用于下载 schema，前者才用于执行查询 - 遇到
Unknown directive @model这类报错？不是 WebStorm 问题，是 schema 里用了服务端扩展指令，但插件默认不识别。得去Settings | Languages & Frameworks | GraphQL手动启用AWS AppSync或Amplify类型定义支持
别信网上抄来的旧配置——2018 年的 js-graphql-intellij-plugin 配置格式和现在官方插件不兼容，字段名和嵌套层级全变了。
写了 query 却没提示、跳转失效，大概率是作用域没对上
WebStorm 会为每个 graphql.config.json 里的 projects 创建独立作用域。如果你的查询文件不在对应 project 的 includes 范围内，哪怕 schema 加载成功，补全也完全不工作。
- 检查配置里有没有
includes字段，例如："includes": ["src/**/*.graphql", "src/**/*.ts"]—— 缺了这句，.ts里的gql模板就不会被纳入 GraphQL 作用域 - 多 schema 项目（比如同时连了 user-api 和 billing-api）必须为每个 schema 单独配一个
project，并确保文件路径匹配对应includes，否则 WebStorm 会随机选一个 schema 去校验你的 query - 改完配置后，别只刷新编辑器，要右键项目根目录 → Reload project from graphql.config.json，否则缓存可能卡住老 schema
典型表现：schema 文件里明明有 User.name 字段，但 query 里写 name 就没提示，Ctrl+Click 提示 “Cannot find declaration to go to”。
想直接在 WebStorm 里跑 query 看结果？endpoint 配置比想象中严格
WebStorm 的 GraphQL 工具栏（右上角 Play 按钮）只认 endpoints 列表里的地址，而且只支持 POST，header 必须显式声明 Content-Type。
-
endpoints数组里每个对象必须有url和name，缺一不可；name还得和你在 .graphql 文件顶部的# endpoint: xxx注释严格一致 - 如果服务端要求
Content-Type: application/json，但你没在options.headers里写，请求会静默失败（Network 面板都看不到），WebStorm 只显示 “No response” - 变量传不进去？检查
variables是不是合法 JSON（不能有尾逗号、单引号），且变量名和 query 中的$id保持大小写一致
真正麻烦的是环境变量混用场景：.env 文件里的 GRAPHQL_URL 不会被自动注入到 endpoint 配置里，必须手动写死 URL 或用 ${env.GRAPHQL_URL} 语法——而这个语法只在 graphql.config.json 的 endpoints.url 字段里有效，schema 字段不支持。
