WebStorm实现GraphQL字段补全、类型校验和错误高亮的核心是明确配置schema，而非仅安装插件；必须在项目根目录放置graphql.config.json或graphql.config.js，指定可达的schemaPath或schema.request.url，并确保路径正确、服务运行、鉴权头完整，否则补全失效。
WebStorm 要给出 GraphQL 字段补全、类型校验和错误高亮，核心不是装插件，而是让 IDE **明确知道 schema 长什么样**。插件只是载体，schema 才是提示的源头。
graphql.config.json 必须存在且路径/URL 可达
WebStorm 默认不扫描任意 .graphql 文件或猜 schema 结构。它依赖项目根目录（与 package.json 同级）的 graphql.config.json 或 graphql.config.js。没有这个文件，补全基本失效。
- 最简可用配置至少含
schema.request.url（推荐远程 introspection）或schemaPath（本地 SDL 文件） - 用
schemaPath时，路径必须相对项目根，比如"./src/graphql/schema.graphql"，不能写file:./schema.graphql - 如果填的是
http://localhost:4000/graphql，请确认服务真在运行——Docker 容器内访问localhost会失败，得换host.docker.internal或宿主机 IP - 远程 endpoint 若需鉴权，
schema.request.options.headers.Authorization必须带有效 token，否则静默加载失败，IDE 不报具体错误
gql 模板字符串要手动或自动注入语言
写 gql`query { user { id } }` 时，WebStorm 默认当普通 JS 字符串处理，不会触发 GraphQL 补全。这不是 bug，是设计行为。
- 临时解决：光标进模板字符串内部（比如放在
{后），按Alt + Enter（macOS 是Option + Enter），选Inject language or reference → GraphQL - 一劳永逸：进
Settings → Editor → Language Injections，点+，Pattern 填gql，Language 选GraphQL；注意这只对 JS/TS 中的 tagged template 生效，PHP 或纯字符串拼接无效 - 别混淆
gql和graphql标签名——WebStorm 内置只认gql（Apollo 风格），自定义标签名需额外配 Pattern
GraphQL 控制台执行查询前先选对 endpoint
在 .graphql 文件里点右上角 ▶️ 运行，WebStorm 默认只用配置中 endpoints[0]，但它**不会自动继承 schema.request.options.headers**。如果你的 API 需要 Authorization，必须在 endpoints 项里单独写一遍。
-
endpoints数组至少一项，url必须可直连（避免localhost在容器场景下失效） -
options.headers.Authorization和options.credentials（如"omit"）必须显式声明，漏掉就 401，控制台只显示模糊的Network error - 开发环境 endpoint 关了 introspection？补全会断，但语法高亮还在——这是典型“有高亮无字段”的信号
最容易被忽略的是 schema 加载过程完全静默：没提示、没日志、没弹窗。一旦补全异常，第一反应不该是重装插件，而是打开 graphql.config.json 逐行核对 schema 来源是否真实可达、headers 是否完整、路径是否写错相对基准。WebStorm 的 GraphQL 支持强依赖配置的精确性，而不是“差不多能用”。
