先确认语言模式是否生效：vscode默认不识别.graphql/.gql文件，需手动设为graphql语言或在settings.json中配置"files.associations"映射，重启窗口后右下角显示“graphql: connected”；若字段标红、无补全，则schema未加载成功，须检查graphql.config.js中schema路径是否正确、远程endpoint是否允许cors及introspection。

GraphQL 文件没提示？先检查语言模式是否生效

VSCode 默认不把 .graphql 或 .gql 文件当 GraphQL 解析，装了插件也没用。右下角显示 “Plain Text” 就是铁证。

• 手动点右下角语言标识 → 选 “GraphQL”
• 或在 settings.json 里加："files.associations": {"*.graphql": "graphql", "*.gql": "graphql"}
• 改完必须 重启窗口（Ctrl+Shift+P → Developer: Reload Window 不够）
• 确认当前文件右下角变成 “GraphQL” 且后面带冒号和连接状态（如 GraphQL: connected）

智能提示标红或字段不补全？schema 没加载成功

语法高亮能出，但字段名标红、Ctrl+Click 跳转灰掉、IntelliSense 只给基础字符串建议——说明插件根本没读到 schema。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 项目根目录必须有 graphql.config.js 或 graphql.config.yml，旧版 .graphqlrc 已被主流插件弃用
• 配置至少含 schema 字段：本地文件写 schema: "./schema.graphql"；远程服务写 schema: "http://localhost:4000/graphql"
• Windows 用户注意路径分隔符：用正斜杠 schema: "schema/schema.graphql"，别用反斜杠
• 远程 endpoint 必须允许 CORS，且 introspection 查询未被禁用（否则静默失败）

JS/TS 里 gql 模板字符串没提示？标签名和类型声明要对齐

插件默认只识别 gql 标签，且依赖类型系统推导返回结构。写 graphql`...` 或拼接字符串都会失效。

• 确保已安装 graphql-tag：npm i -D graphql-tag
• 在 tsconfig.json 或 jsconfig.json 的 compilerOptions 中加："types": ["graphql-tag"]
• 若用自定义标签（如 query），需在 settings.json 显式声明："graphql.taggedTemplateLiteralName": ["gql", "query"]
• gql 必须单独成行调用，const q = gql`` + '' 或嵌在对象属性里会直接让插件失焦

格式化不起作用？graphql-config 是唯一事实来源

VSCode 的 GraphQL 扩展（如 GraphQL for VSCode）不读 ESLint 或 Prettier 配置，它只认 graphql-config 提供的项目级上下文。

• 必须安装 graphql-config 作为 dev 依赖：npm install --save-dev graphql-config
• graphql.config.js 中除了 schema，还得配 documents 字段，例如：documents: "./src/**/*.{graphql,gql}"
• 格式化行为由扩展内置规则驱动，无需额外装 Prettier 插件；但若想统一风格，可在 graphql.config.js 里加 extensions: { prettier: { semi: false } }（需插件支持）
• 改完配置后，务必打开 Output 面板（Ctrl+Shift+U），选 “GraphQL”，看日志里有没有 Loaded schema from... 成功记录

真正卡住人的地方往往不是插件装没装，而是 graphql.config.js 里一个路径写错、一个斜杠方向反了、或者 Output 面板里那条被忽略的加载失败日志。