必须安装 graphql for vscode（prisma 维护），而非已废弃的 graphql language service 或侧重客户端的 apollo graphql；装完需见状态栏“graphql: connected”，否则 schema 未连上，重启 vscode 才生效。
GraphQL for VSCode 插件必须装对，别被名字骗了
VSCode 市场里搜 “GraphQL” 出来的插件有十几个，但真正能支撑请求调试链路的只有 GraphQL for VSCode（Prisma 团队维护）。GraphQL Language Service 已废弃，装了会导致 .graphql 文件不亮、补全失效；Apollo GraphQL 侧重 client 代码生成，不负责请求发送。
装完后打开任意 .graphql 文件，右下角状态栏必须显示 GraphQL: connected。不显示就说明 schema 没连上——重启 VSCode 才生效，仅重载窗口不够。
schema 路径必须本地化，远程 endpoint 容易静默失败
调试阶段最稳的方式是用本地 schema 文件，而不是直连 http://localhost:4000/graphql。CORS、鉴权、introspection 关闭都会让插件加载失败，且无任何界面提示。
在项目根目录建 graphql.config.yml，内容至少包含：
{
"schema": "./schema.graphql",
"documents": ["src/**/*.{ts,tsx,js,jsx,graphql,gql}"]
}
注意几点：
-
schema路径是相对于graphql.config.yml所在位置，不能写./src/schema.graphql（除非 config 文件也在 src 里） - Windows 用户禁用反斜杠：
schema: "schema\schema.graphql"会解析失败，得写成schema: "schema/schema.graphql" - 如果用的是 introspection JSON，得改名成
schema.json并在配置里显式声明"schema": "./schema.json"，插件默认不认schema.graphql这种 SDL 格式
GraphQL Request 插件发请求，注释格式不能错
要直接在 VSCode 里发请求，得装 GraphQL Request（作者 jimmydief）。它不依赖外部服务，纯靠 VSCode 内置 fetch。
请求必须写在 .graphql 文件中，且顶部用严格格式注释声明 endpoint：
# GraphQL Request: http://localhost:4000/graphql
query GetUser {
user(id: "1") {
name
email
}
}
光标放在 query 内，按 Ctrl+Alt+R（Win/Linux）或 Cmd+Alt+R（macOS）触发请求。响应默认出现在右侧面板。
常见失败原因：
-
NetworkError when attempting to fetch resource：endpoint 地址错、服务没启动、返回非 2xx 状态码（比如 400 带 GraphQL 错误） - mutation 报
Variable $input is not defined：变量块缺失或格式不对，必须显式写variables注释块 - 请求没发出去：检查文件语言模式是否为
GraphQL（右下角点“Plain Text”手动切），否则插件不激活
TS 里写 gql 模板没提示？类型声明和标签名都要对齐
插件默认只识别 gql`` 和 graphql`` 这两种前缀。如果你用的是 import { gql } from '@apollo/client' 或自定义 tag 名（如 query），必须手动配两件事：
第一，在 settings.json 加：
"graphql.taggedTemplateLiteralName": ["gql", "graphql", "query"]
第二，在项目里加 graphql.d.ts（放 src/@types 或根目录 types 下）：
import { TypedDocumentNode } from '@apollo/client';
declare global {
namespace GraphQLTag {
export interface DocumentNode<t any v="any"> extends TypedDocumentNode<t v> {}
}
}
declare function gql(literals: TemplateStringsArray, ...placeholders: any[]): GraphQLTag.DocumentNode;</t></t>
另外，gql 模板必须单独成行、前后无拼接：const q = gql`...` 可以，const q = gql`...` + '' 或嵌在对象属性里会直接让插件失焦。
最常被忽略的是：修改 graphql.config.yml 后，必须右键任意 .graphql 文件 → “Reload GraphQL Schema”，不是改完就自动生效，也不是重启 VSCode 就行。
