先确认语言模式是否生效：VSCode默认不识别.graphql/.gql文件，需手动设为GraphQL语言或在settings.json中配置"files.associations"映射，重启窗口后右下角显示“GraphQL: connected”；若字段标红、无补全，则schema未加载成功，须检查graphql.config.js中schema路径是否正确、远程endpoint是否允许CORS及introspection。
GraphQL 文件没提示？先检查语言模式是否生效
VSCode 默认不把 .graphql 或 .gql 文件当 GraphQL 解析，装了插件也没用。右下角显示 “Plain Text” 就是铁证。
- 手动点右下角语言标识 → 选 “GraphQL”
- 或在
settings.json里加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"} - 改完必须 重启窗口（
Ctrl+Shift+P→Developer: Reload Window不够） - 确认当前文件右下角变成 “GraphQL” 且后面带冒号和连接状态（如
GraphQL: connected）
智能提示标红或字段不补全？schema 没加载成功
语法高亮能出，但字段名标红、Ctrl+Click 跳转灰掉、IntelliSense 只给基础字符串建议——说明插件根本没读到 schema。
- 项目根目录必须有
graphql.config.js或graphql.config.yml，旧版.graphqlrc已被主流插件弃用 - 配置至少含
schema字段：本地文件写schema: "./schema.graphql"；远程服务写schema: "http://localhost:4000/graphql" - Windows 用户注意路径分隔符：用正斜杠
schema: "schema/schema.graphql"，别用反斜杠 - 远程 endpoint 必须允许 CORS，且 introspection 查询未被禁用（否则静默失败）
JS/TS 里 gql 模板字符串没提示？标签名和类型声明要对齐
插件默认只识别 gql 标签，且依赖类型系统推导返回结构。写 graphql`...` 或拼接字符串都会失效。
- 确保已安装
graphql-tag：npm i -D graphql-tag - 在
tsconfig.json或jsconfig.json的compilerOptions中加："types": ["graphql-tag"] - 若用自定义标签（如
query），需在settings.json显式声明："graphql.taggedTemplateLiteralName": ["gql", "query"] -
gql必须单独成行调用，const q = gql`` + ''或嵌在对象属性里会直接让插件失焦
格式化不起作用？graphql-config 是唯一事实来源
VSCode 的 GraphQL 扩展（如 GraphQL for VSCode）不读 ESLint 或 Prettier 配置，它只认 graphql-config 提供的项目级上下文。
- 必须安装
graphql-config作为 dev 依赖：npm install --save-dev graphql-config -
graphql.config.js中除了schema，还得配documents字段，例如：documents: "./src/**/*.{graphql,gql}" - 格式化行为由扩展内置规则驱动，无需额外装 Prettier 插件；但若想统一风格，可在
graphql.config.js里加extensions: { prettier: { semi: false } }（需插件支持） - 改完配置后，务必打开
Output面板（Ctrl+Shift+U），选 “GraphQL”，看日志里有没有Loaded schema from...成功记录
graphql.config.js 里一个路径写错、一个斜杠方向反了、或者 Output 面板里那条被忽略的加载失败日志。 
