必须只装 GraphQL for VSCode 插件并重启 VSCode，确保右下角显示 GraphQL: connected；schemaPath 要用相对于 graphql.config.yml 的正确路径（如 schema.graphql），JS/TS 中 gql 模板须单独成行且匹配标签名，补全失效时需通过 Output 面板查日志。
只装 GraphQL for VSCode 一个插件，其他全删——装错或装多，补全、跳转、校验全部失效。
GraphQL for VSCode 插件必须手动重载才生效
装完插件后，VSCode 不会自动激活 Language Server。右下角不显示 GraphQL: connected，就等于没连上 schema，所有智能提示都只是摆设。
- 必须重启 VSCode（不是“重载窗口”），否则状态栏永远不出现连接标识
- 打开任意
.graphql文件，右下角语言模式要显示GraphQL，不是Plain Text；若不是，进settings.json手动加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"} - 状态栏显示
GraphQL: connected后，悬停字段应有类型提示，灰色下划线表示可跳转定义
graphql.config.yml 中的 schemaPath 路径不能带 ./
YAML 解析器会忽略 ./ 前缀，写成 ./schema.graphql 等价于 schema.graphql，但一旦当前工作区不是项目根目录，路径就直接失效。
- 正确写法是：
schema: schema.graphql或schema: src/graphql/schema.graphql - 路径是相对于
graphql.config.yml所在目录，不是 VSCode 打开的文件夹根目录 - Windows 用户统一用正斜杠
/，反斜杠\在 YAML 里是转义符，会导致解析失败 - 多个 schema 文件需用数组：
schema: ["schema/types.graphql", "schema/queries.graphql"]
JS/TS 里 gql 模板字符串必须单独成行且标签名匹配
插件默认只识别 gql 标签，且语法结构稍有偏差（比如拼接、嵌套）就会让 Language Server 失焦，补全立刻消失。
前端设计优化skill
下载
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
立即学习“前端免费学习笔记（深入）”；
- 合法写法：
const query = gql`{ user { id } }`（单独一行、无前后拼接） - 非法写法：
const query = gql`` + '{ user { id } }'或query: gql`...`（作为对象属性值） - 若用
graphql或query标签，必须在settings.json中声明："graphql.taggedTemplateLiteralName": ["gql", "graphql"] - TypeScript 项目还需全局声明
gql类型，否则返回类型推导退化为any，补全只剩字段名字符串匹配
补全失效时，Output 面板是唯一诊断入口
Language Server 出错时，VSCode 界面零提示，不会弹窗、不标红、不报错——你只会发现“没补全”“Ctrl+Click 灰掉”“字段标红但点不开”。这时候必须看日志。
- 快捷键
Ctrl+Shift+U打开 Output 面板，下拉选GraphQL - 常见错误：
Unable to load schema from schema.graphql（路径错 / 文件不存在 / 内容不是 SDL）、Failed to fetch introspection（CORS / 401 / introspection 关闭） - 远程 endpoint 若需鉴权，必须在
graphql.config.js中通过extensions.endpoints.default.headers注入 token，硬编码 token 到配置里属于高危操作
最常被忽略的是：schema 文件内容必须是标准 SDL（Schema Definition Language），不能是 introspection JSON 输出。导出 schema 请用 npx graphql-cli download-schema，别手动生成或复制 GraphiQL 的 raw response。
