如何设置VSCode GraphQL开发环境？前端专家必装的语法提示插件是？

本文共计888个文字，预计阅读时间需要4分钟。

安装GraphQL for VSCode插件后，其他全部删除——装错或装多，补全、跳转、验证全部失效。

GraphQL for VSCode 插件必须手动重载才生效

装完插件后，VSCode 不会自动激活 Language Server。右下角不显示 GraphQL: connected，就等于没连上 schema，所有智能提示都只是摆设。

• 必须重启 VSCode（不是“重载窗口”），否则状态栏永远不出现连接标识
• 打开任意 .graphql 文件，右下角语言模式要显示 GraphQL，不是 Plain Text；若不是，进 settings.json 手动加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"}
• 状态栏显示 GraphQL: connected 后，悬停字段应有类型提示，灰色下划线表示可跳转定义

graphql.config.yml 中的 schemaPath 路径不能带 ./

YAML 解析器会忽略 ./ 前缀，写成 ./schema.graphql 等价于 schema.graphql，但一旦当前工作区不是项目根目录，路径就直接失效。

• 正确写法是：schema: schema.graphql 或 schema: src/graphql/schema.graphql
• 路径是相对于 graphql.config.yml 所在目录，不是 VSCode 打开的文件夹根目录
• Windows 用户统一用正斜杠 /，反斜杠 \ 在 YAML 里是转义符，会导致解析失败
• 多个 schema 文件需用数组：schema: ["schema/types.graphql", "schema/queries.graphql"]

JS/TS 里 gql 模板字符串必须单独成行且标签名匹配

插件默认只识别 gql 标签，且语法结构稍有偏差（比如拼接、嵌套）就会让 Language Server 失焦，补全立刻消失。

立即学习“前端免费学习笔记（深入）”；

• 合法写法：const query = gql`{ user { id } }`（单独一行、无前后拼接）
• 非法写法：const query = gql`` + '{ user { id } }' 或 query: gql`...`（作为对象属性值）
• 若用 graphql 或 query 标签，必须在 settings.json 中声明："graphql.taggedTemplateLiteralName": ["gql", "graphql"]
• TypeScript 项目还需全局声明 gql 类型，否则返回类型推导退化为 any，补全只剩字段名字符串匹配

补全失效时，Output 面板是唯一诊断入口

Language Server 出错时，VSCode 界面零提示，不会弹窗、不标红、不报错——你只会发现“没补全”“Ctrl+Click 灰掉”“字段标红但点不开”。这时候必须看日志。

• 快捷键 Ctrl+Shift+U 打开 Output 面板，下拉选 GraphQL
• 常见错误：Unable to load schema from schema.graphql（路径错 / 文件不存在 / 内容不是 SDL）、Failed to fetch introspection（CORS / 401 / introspection 关闭）
• 远程 endpoint 若需鉴权，必须在 graphql.config.js 中通过 extensions.endpoints.default.headers 注入 token，硬编码 token 到配置里属于高危操作

最常被忽略的是：schema 文件内容必须是标准 SDL（Schema Definition Language），不能是 introspection JSON 输出。导出 schema 请用 npx graphql-cli download-schema，别手动生成或复制 GraphiQL 的 raw response。