必须安装 graphql for vscode 插件并重启 vscode，配置正确的 graphql.config.yml 路径（相对于配置文件位置）、关联 .graphql 文件类型、声明 tagged template literals，并通过 output 面板查看 graphql 日志诊断问题。
装错插件或路径配错，补全就静默失效——VSCode 不会报错，你只会发现字段不提示、Ctrl+Click 灰掉、悬停没类型。
只装 GraphQL for VSCode（Prisma 团队维护）
VSCode 市场里搜 “GraphQL” 出十几个插件，但真正能连 schema、做字段补全、跳转定义的只有 GraphQL for VSCode（作者 Prisma）。别碰 GraphQL Language Service——它已废弃，装了反而让 .graphql 文件变 Plain Text，高亮和补全全崩。
装完必须重启 VSCode（不是重载窗口），否则右下角永远不显示 GraphQL: connected。看到这个标识，才代表 Language Server 已激活、schema 可用了。
- 打开任意
.graphql文件，右下角语言模式必须是GraphQL，不是Plain Text - 如果还是 Plain Text，在
settings.json手动加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"} - 禁用所有其他 GraphQL 相关插件，尤其是
GraphQL Tools、Apollo GraphQL（后者专注 client 生成，不负责补全）
graphql.config.yml 路径必须写对（不是相对项目根目录）
插件靠 graphql.config.yml 找 schema，但路径规则反直觉：它是相对于该配置文件所在位置，不是 VSCode 打开的工作区根目录。写错就等于没配，补全直接归零。
正确写法示例（放在项目根目录）：
{
"schema": "schema.graphql",
"documents": ["src/**/*.{ts,tsx,js,jsx,graphql,gql}"]
}
-
./schema.graphql中的./会被 YAML 解析器忽略，等价于schema.graphql；写成src/schema.graphql就错了（除非 config 文件也在src里） - Windows 用户禁用反斜杠：
schema\schema.graphql是非法 YAML，必须用正斜杠schema/schema.graphql - 多个 schema 文件？用数组：
"schema": ["schema/types.graphql", "schema/queries.graphql"] - 用的是
schema.json（introspection 输出）？配置里就得写"schema": "schema.json"，插件默认不认schema.graphql这种 SDL 格式
TS/JS 里 gql 模板字符串要能补全，得两步走
插件默认只识别 gql`...` 或 graphql`...` 这种独立模板字面量，且只在它能解析 AST 的前提下工作。光有插件，import { gql } from 'graphql-tag' 在 TS 里照样没字段提示。
- 在
settings.json加声明："graphql.taggedTemplateLiteralName": ["gql", "graphql"] - TypeScript 项目必须全局声明类型：新建
src/@types/graphql.d.ts，内容为：declare module 'graphql-tag' { export function gql(literals: TemplateStringsArray, ...placeholders: any[]): any; } - 写法必须规范：单独一行、无拼接、不嵌套在对象属性里。合法：
const query = gql`{ user { id } }`；非法：const q = gql`` + '{ user { id } }'或query: gql`...`
补全失效时，唯一有效诊断方式是看 Output 面板
Language Server 出错，VSCode 界面零提示——不弹窗、不标红、状态栏也不变。你只会觉得“怎么又不提示了”。这时候必须打开 Output 面板（Ctrl+Shift+U），下拉选 GraphQL，看日志里有没有 Unable to load schema from、Failed to parse schema 这类错误。
常见日志线索：
-
ENOENT: no such file or directory, open 'schema.graphql'→ 路径错或文件真不存在 -
NetworkError when attempting to fetch resource→ 如果配的是 URL，服务没启、CORS 拦了、或返回非 2xx -
Unexpected token→schema.graphql里有语法错误（比如多了一个逗号）
本地 schema 文件比 endpoint 更稳；每次后端 schema 变更，记得手动更新它，否则补全提示就过期了。
