必须只装GraphQL for VSCode插件并完全重启VSCode，确保右下角显示“GraphQL: connected”；否则Language Server未连接，.graphql文件字段标红、跳转失效。
必须只装 GraphQL for VSCode 一个插件，其他 GraphQL 相关扩展全删；右下角不显示 GraphQL: connected，智能提示就等于没启动。
为什么 .graphql 文件里字段标红、Ctrl+Click 跳转灰掉
不是语法错，是 Language Server 根本没连上 schema。VSCode 默认把 .graphql 当纯文本，即使装了插件也无效。
- 先点右下角语言模式 → 手动选
GraphQL；或在settings.json加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"} - 改完必须 完全重启 VSCode（
Developer: Reload Window不够） - 重启后右下角要出现
GraphQL: connected，不是GraphQL: disconnected或Plain Text - 若仍标红，打开
Output面板（Ctrl+Shift+U），选GraphQL查日志——90% 是schema路径错或文件不存在
graphql.config.yml 中 schema 路径怎么写才有效
YAML 解析器会忽略 ./ 前缀，且路径是相对于 graphql.config.yml 所在目录，不是项目根目录或 VSCode 工作区根目录。
- 错误写法：
schema: ./schema.graphql（等价于schema.graphql，但一旦 config 不在项目根，就失效） - 正确写法：
schema: schema.graphql或schema: src/graphql/schema.graphql - Windows 用户必须用正斜杠
/，反斜杠\是 YAML 转义符，会导致解析失败 - 远程 schema 写法：
schema: http://localhost:4000/graphql，但 endpoint 必须允许 CORS 且未禁用 introspection
JS/TS 里 gql 模板字符串没提示？标签和结构都得对
插件默认只识别独立成行的 gql 标签，且依赖类型系统推导返回结构。稍有偏差，Language Server 就失焦。
- 合法写法：
const query = gql`{ user { id } }`（单独一行、无拼接、无嵌套） - 非法写法：
const q = gql`` + '{ user { id } }'或query: gql`...`（作为对象属性值） - 若用自定义标签如
graphql，需在settings.json显式声明："graphql.taggedTemplateLiteralName": ["gql", "graphql"] - TypeScript 项目还需在
tsconfig.json的compilerOptions.types中加"graphql-tag"，否则返回类型退化为any
补全有但字段名提示不准，或突然失效
常见于本地 schema 长期未更新，或配置中漏了 documents 字段导致插件无法感知操作文件范围。
- schema 必须是 SDL 格式（不是 introspection JSON），内容不合法会导致静默失败
- 推荐定期用
npm run graphql:download（配合get-graphql-schema）同步远程 schema - 确保
graphql.config.yml含documents字段，例如：documents: "./src/**/*.{graphql,gql}"，否则插件无法建立查询与 schema 的关联 - 多 schema 场景下，不要用数组拼一堆
.graphql文件——优先合并或用extensions.endpoints分环境管理
最常被忽略的是：graphql.config.yml 位置不对、路径没对齐 config 文件所在目录、以及重启不彻底。这些地方一错，整个智能提示链就断在第一步，后面调任何参数都没用。
