必须安装GraphQL for VSCode插件并正确配置graphql.config.yml/js：指定schemaPath（推荐本地文件路径，注意YAML路径解析规则）、documents，手动关联.graphql/.gql文件语言模式，通过Output面板排查Language Server错误，定期同步本地Schema以保证补全准确。
GraphQL插件必须装这一个：GraphQL for VSCode
VSCode原生不支持GraphQL语法解析和Schema感知，光靠GraphQL语言模式只能高亮、无法补全字段或校验类型。真正能联动后端Schema、自动提示字段、跳转定义、报错提示的，只有GraphQL for VSCode（作者：Prisma）——不是GraphQL Language Service，也不是GraphQL Tools，后者已归档且不维护。
安装后需手动配置才能生效，否则只是个花瓶：
- 项目根目录必须有
graphql.config.yml或graphql.config.js，用于声明Schema来源（如url、schemaPath或documents） - 若用
url方式（如http://localhost:4000/graphql），需确保服务已启动且CORS允许Origin: file://（本地开发时常见403） - 推荐优先用
schemaPath指向本地.graphql文件，避免网络依赖和鉴权问题
schemaPath配置写法与常见路径陷阱
graphql.config.yml里schemaPath看着简单，但路径解析规则和VSCode工作区绑定紧密，极易写错：
- 路径是相对于
graphql.config.yml所在目录，不是VSCode打开的文件夹根目录 - 支持glob，比如
schema/**/*.graphql，但不能写成./schema/*.graphql（./会被忽略） - 如果Schema拆成多个文件（如
types.graphql+queries.graphql），必须用数组：schemaPath: ["schema/types.graphql", "schema/queries.graphql"] - Windows用户注意反斜杠
\在YAML里是转义符，统一用正斜杠/
示例有效配置：
schema: ./schema.graphql documents: "src/**/*.graphql"
查询文件后缀和语言模式必须匹配
VSCode不会自动把.gql或.graphql文件识别为GraphQL语言，即使装了插件。必须手动设置：
- 打开任意
.graphql文件 → 点右下角语言标识（如“Plain Text”）→ 选“GraphQL” - 或在
settings.json中加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"} - 不匹配会导致补全完全失效，且
Ctrl+Click跳转定义失败，但错误提示仍可能显示（容易误判配置成功）
补全失效时先查GraphQL输出面板
插件后台运行的Language Server出错时，VSCode界面毫无提示，只表现为“没补全”“跳转灰掉”。必须打开Output面板（Ctrl+Shift+U），在下拉菜单选GraphQL：
- 看到
Failed to load schema from ...：检查schemaPath路径是否存在、是否拼写错误 - 看到
Unexpected token：通常是Schema文件含JS注释（//）或ES6语法（插件只认标准SDL） - 看到
Network error且用的是url：确认服务响应头含Access-Control-Allow-Origin: *，或改用本地schemaPath
重启VSCode本身不解决问题，得重启GraphQL Language Server：命令面板（Ctrl+Shift+P）搜GraphQL: Restart Service。
Schema感知不是一劳永逸的事——后端字段增减后，本地schema.graphql不更新，补全就过期；而自动拉取又卡在CORS或鉴权上。最稳的节奏是：开发时用本地Schema文件 + 手动同步更新，上线前再切回URL做最终校验。
