应安装官方graphql插件而非js graphql，配置graphql.config.json指定schema地址和鉴权头，并启用apollo/relay支持以实现js/ts中gql模板字符串的语法高亮与字段补全。
直接装 GraphQL 插件，别装“js GraphQL”
WebStorm 官方从 2025 年起已将 GraphQL 支持统一收归为内置推荐插件 GraphQL，而旧版第三方插件 js GraphQL（作者 jimkyndemeyer）早已停止维护，且与新版 WebStorm（2025.1+）存在兼容问题——比如 schema 自动加载失败、gql 模板字符串不识别、endpoint 请求头被忽略等。
实操建议：
- 打开设置：
Ctrl+Alt+S→Plugins→ Marketplace 选项卡 - 搜索
GraphQL（注意：不是 “js GraphQL”，也不是 “GraphQL Language Service”）→ 点击Install - 安装后必须重启 WebStorm，否则
.graphql文件无语法高亮、无字段补全 - 确认已禁用旧插件：
Plugins→Installed页签里搜js GraphQL，如有则Disable或Uninstall
配置 graphql.config.json 是补全和校验的前提
插件装完只是“有功能”，但没配 graphql.config.json，它根本不知道你的 schema 长什么样，也就没法做字段提示、类型跳转或错误标红——你写的 query 即使拼错字段名，IDE 也完全沉默。
常见错误现象：写 user { namme }（故意拼错），但 WebStorm 不报错、不提示正确字段是 name。
实操建议：
- 在项目根目录（与
package.json同级）新建graphql.config.json - 最简可用配置只需指定
schema.request.url和endpoints，不用写 introspectionQuery 手动下载文件 - 如果服务端启用了鉴权（如 Bearer Token），务必在
endpoints[0].options.headers.Authorization中填入有效 token，否则 schema 加载失败且无明确报错 - 避免路径陷阱：不要用
file:./schema.graphql做本地 schema，除非你每次手动更新它；优先走远程 introspection
在 .graphql 文件里发请求，得先选对 endpoint
WebStorm 的 GraphQL 控制台（点击右上角 ▶️ 运行按钮）默认只用第一个 endpoints，但它不会自动读取你配置里的 Authorization 头——如果你漏写了 credentials: "omit" 或 header 格式不对，请求会静默 401，控制台只显示 Network error，连具体 HTTP 状态码都不给。
使用场景：调试 query、验证 fragment 结构、快速测新字段是否上线。
实操建议：
- 确保
graphql.config.json中endpoints数组至少有一项，且url可直连（别写 localhost —— Docker 或 remote dev server 下可能不通） - header 中的 token 值别硬编码明文，改用环境变量：
"Authorization": "Bearer ${env:GRAPHQL_TOKEN}"，然后在 WebStorm 的Run Configuration里设环境变量 - 运行前点一下右上角 endpoint 下拉框，确认选中的是你配置的那个名字（如
Default (http://localhost:4000/graphql)），不是灰色的Not configured - 遇到
currentError提示，别狂点刷新；先看控制台底部状态栏有没有红色网络图标，再检查终端里 GraphQL 服务是否真在运行
JS/TS 里用 gql 模板字面量，要开 Apollo/Relay 支持
即使装了 GraphQL 插件，默认也不会识别 gql`query GetUser { id }` 这类 JS/TS 中的模板字符串——它会被当普通字符串，没有语法高亮、无字段补全、也不能跳转到 schema 定义。
性能影响：不开这项支持，插件只扫描 .graphql 文件，对 JS/TS 文件完全“视而不见”，等于浪费了 70% 的日常编码场景。
实操建议：
- 进设置：
Ctrl+Alt+S→Languages & Frameworks→GraphQL - 勾选
Apollo GraphQL（Vue/Angular/React 通用）或Relay（仅 Relay 项目），二者可共存 - 确认项目里已安装
graphql和apollo-boost/@apollo/client等依赖，否则插件可能因缺少graphql类型定义而降级处理 - 如果用的是
gql以外的 tag 名（比如graphql或自定义q），需在设置里手动添加到Tag names列表中
最容易被忽略的一点：graphql.config.json 必须存在且语法合法，哪怕只有一行 {}，插件才会启动 schema 发现流程；空文件、JSON 格式错误、或放在子目录下，都会导致整个 GraphQL 功能“半瘫痪”——看起来装好了，实际啥也不干。
