根本原因是language server未连上schema：需重启vscode（非重载）、确保右下角显示graphql: connected、graphql.config.yml置于根目录、.graphql文件语言模式设为graphql、schema路径正确且格式合法。
为什么装了插件还是没补全、没跳转？
不是插件没装对，是 Language Server 没连上 schema。GraphQL for VSCode 插件装完必须重启 VSCode（不是重载窗口），否则右下角永远不显示 GraphQL: connected。状态栏没这个标识，所有字段补全、类型悬停、Ctrl+Click 跳转都失效。
常见卡点：
- 右下角语言模式显示的是
Plain Text而不是GraphQL：手动点击切换，或在settings.json加"files.associations": {"*.graphql": "graphql", "*.gql": "graphql"} -
graphql.config.yml或.graphqlrc放错位置：必须放在工作区根目录，且路径相对于该配置文件本身（./schema.graphql等价于schema.graphql，YAML 会忽略./） - schema 文件路径写错或内容非法：SDL 格式（不是 introspection JSON）；Windows 用户务必用正斜杠
/，反斜杠\会被 YAML 解析为转义符 - 多文件 schema：用数组写法，如
schema: ["schema/types.graphql", "schema/queries.graphql"]
怎么在 .graphql 文件里直接发请求？
靠 GraphQL Request 插件（ID：jimmydief.vscode-graphql-request），不是靠 GraphQL for VSCode。前者负责发请求，后者只管编辑体验，两者不冲突但职责分明。
关键写法：
- 必须把 endpoint 写在查询上方的注释里：
# GraphQL Request: http://localhost:4000/graphql - query/mutation 必须带 operation name：
query GetUser，不能写匿名查询{ user { id } } - 有变量时，必须同时提供变量 JSON 块（光标在 query 内，按
Ctrl+Alt+R才触发） - 响应默认弹出在右侧面板；失败时不报错弹窗，去
Output面板选GraphQL Request通道看具体错误
TS/JS 里写 gql 模板没提示？
插件默认只识别独占一行、标签名严格匹配的 gql 模板。任何拼接、嵌套、换行错位都会让 Language Server 失焦。
合法写法示例：
const GET_USER = gql`
query GetUser($id: ID!) {
user(id: $id) {
id
name
}
}
`;
非法写法：
const q = gql`` + '{ user { id } }'-
query: gql`{ user { id } }`（作为对象属性值） - 模板字符串前后有空格或换行不规范
TypeScript 项目还必须全局声明类型，在 graphql.d.ts 里加：
declare module 'graphql-tag' {
export function gql(literals: TemplateStringsArray, ...args: any[]): any;
}
调试失败时先盯哪几个地方？
VSCode 的 GraphQL 工具链几乎不报明显错误——它只会“静默失效”。真正有用的线索藏在三处：
-
Output面板 → 切换到GraphQL或GraphQL Request通道，看是否有Network error、Parse error或Schema not loaded - 右下角语言模式是否为
GraphQL，状态栏是否显示GraphQL: connected - 终端里跑
curl -X POST http://localhost:4000/graphql --data '{"query":"{__schema{types{name}}"}'} -H "Content-Type: application/json"，确认服务本身可连通且返回 2xx
最常被忽略的一点：本地开发服务（如 Apollo Server）默认不允许 Origin: file://，CORS 报 403 时，VSCode 里只显示空白响应或 Network error，根本不会提示是跨域问题。
