应安装prisma发布的graphql插件；装对后打开.graphql或含gql的ts/js文件，状态栏显示“graphql: connected”，且重启vscode才生效。
GraphQL插件装哪个、怎么确认装对了
VSCode 官方市场里叫 GraphQL 的插件只有一个——作者是 Prisma（不是 GraphQL Tools 或 Apollo 那几个旧版）。装错会导致 schema 无法加载、补全完全不触发。装完后打开一个 .graphql 文件或带 gql 模板字面量的 .ts/.js 文件，右下角状态栏应显示 GraphQL: connected，否则说明没连上 schema。
- 必须重启 VSCode 才能生效，仅重载窗口不够
- 如果用的是 Apollo Client，确保项目里有
apollo.config.js或graphql.config.js，否则插件找不到 schema 入口 - 插件默认只识别
gql标签；若用graphql函数或其它标签名，得在settings.json里配"graphql.taggedTemplateLiteralName": ["gql", "graphql"]
schema 怎么让插件读到（本地文件 or 远程 endpoint）
自动补全依赖 schema 定义，插件不会自己猜字段。它要么从本地 schema.graphql 文件读，要么从运行中的 GraphQL endpoint 抓取（需服务开启 introspection）。两者不能混用，且路径/URL 必须显式声明。
- 本地 schema：在
graphql.config.js中写schema: './src/schema.graphql'，路径必须是项目根目录下的相对路径 - 远程 schema：写
schema: 'http://localhost:4000/graphql'，但 endpoint 必须允许 CORS，且返回的 schema 不能被权限拦截（比如某些生产环境会关掉 introspection） - 常见报错
Unable to load schema from ...多半是路径错、文件不存在、或 endpoint 返回 401/403
查询语句里字段不补全？检查这三件事
即使插件和 schema 都就位，补全仍可能失效。核心原因是插件需要明确知道“当前 query 属于哪个 schema 类型”，而它靠语法结构推断——一旦格式不标准，就放弃解析。
-
gql模板字面量必须单独成行，且前后无多余字符：const GET_USER = gql`<br> query GetUser($id: ID!) {<br> user(id: $id) {<br> id<br> name<br> }<br> }<br>`;像const q = gql`...` + ''或嵌套在对象属性里都会让插件失焦 - query 名称必须合法（字母开头，不含空格/特殊符号），否则插件解析失败，字段补全直接关闭
- 如果用了 fragment，确保 fragment 定义在同一个文件或已通过
extensions.graphql.include引入，否则插件看不到 fragment 类型，关联字段就不补全
TS/JS 文件里补全慢或卡顿怎么办
插件会对每个 gql 字符串做 AST 解析 + schema 匹配，schema 越大（尤其含大量 union/interface）、文件越多，延迟越明显。这不是 bug，是设计使然。
- 禁用非必要语言支持：在设置里关掉
GraphQL: Enable JavaScript GraphQL Support，如果只写 TS - 缩小 schema 范围：用
documents字段在graphql.config.js中限定只扫描src/**/*.{graphql,ts,js}，别让它扫 node_modules - 避免在单个文件里堆几十个 query —— 插件会逐个解析，CPU 占用飙升，建议拆分文件或改用 codegen 提前生成类型
schema 加载和补全逻辑藏在后台进程里，没界面反馈，出问题时只会静默失败。最稳妥的验证方式：删掉一个已补全的字段，敲 . 看是否弹出字段列表——不弹就是链路断在某处，得回溯配置和文件结构。
