应安装 graphql for vscode 而非已停更的 apollo 插件，配置 graphql.config.yml 时路径须正确（如 schema: ../schema.graphql）、windows 用正斜杠、多文件用数组，且需手动绑定 .graphql/.gql 文件关联并重启 vscode；js/ts 中 gql 模板字符串需严格格式，补全失败需查 output 面板 graphql 日志。
只装 GraphQL for VSCode，别碰 Apollo 官方插件
VSCode 里名字带 “Apollo” 的 GraphQL 插件（比如 Apollo GraphQL）已多年未维护，装了反而会让状态栏卡在 GraphQL: disconnected，或者 Output 面板反复报 Unable to load schema from。真正能稳定加载本地 schema、支持字段补全和 Ctrl+Click 跳转的，只有 GraphQL for VSCode（作者 Prisma）。装完必须彻底重启 VSCode —— 用 Developer: Reload Window 不生效，Language Server 压根不启动。
graphql.config.yml 路径必须写对，且不能带 ./
插件读取 schema 的路径是相对于 graphql.config.yml 所在目录，不是工作区根目录，也不是当前打开的文件位置。YAML 解析器会忽略 ./ 前缀，所以 ./schema.graphql 和 schema.graphql 等价；但一旦配置文件放在 config/graphql.config.yml，而你写的是 schema.graphql，它就会去 config/ 下找，而不是项目根目录。
- 正确写法示例：
schema: ../schema.graphql（当 config 文件在子目录时） - Windows 用户必须用正斜杠：
schema: schema/schema.graphql，schema\schema.graphql是非法 YAML - 多文件 schema 要用数组：
schema: ["schema/types.graphql", "schema/queries.graphql"] - 远程 endpoint 可写为：
schema: http://localhost:4000/graphql，但需确保服务已启、CORS 开放、introspection 未禁用
文件后缀和语言模式必须手动绑定
VSCode 默认不把 .graphql 或 .gql 当作 GraphQL 语言处理，装了插件也没用。右下角显示 Plain Text 就是铁证。必须进 settings.json 手动加：
"files.associations": {
"*.graphql": "graphql",
"*.gql": "graphql",
"schema.graphql": "graphql"
}
改完要重启 VSCode（不是重载窗口），再打开一个 .graphql 文件，确认右下角显示 GraphQL: connected。如果只显示 GraphQL 没冒号和 connected，说明 schema 没加载成功，得回头查日志。
JS/TS 里 gql 模板字符串没提示？标签名和格式都得卡死
插件默认只识别单独成行、标签名为 gql 的模板字面量，其他写法一律失焦：
- ✅ 正确：
const query = gql`query GetUser { user(id: $id) { name } }`; - ❌ 错误：
const q = gql`` + ''（拼接）、query: gql``（嵌在对象里）、graphql`...`（标签名不对） - 若要用其他标签名（如
graphql），需在settings.json加："graphql.taggedTemplateLiteralName": ["gql", "graphql"] - TypeScript 项目还需声明类型：在
graphql.d.ts中加declare module 'graphql-tag' { export const gql: any; }，否则 TS 不认gql是 GraphQL 片段
最常被忽略的一点：补全失效时 VSCode 绝不报错，只“静默失效”。必须打开 Output 面板（Ctrl+Shift+U），选 GraphQL，看日志里有没有 Starting language server 后的错误 —— 路径错、YAML 解析失败、schema 文件不存在，全在这里暴露。
