需手动配置文件关联和graphql-config：在settings.json中添加graphql文件关联，项目根目录创建graphql.config.yml/js指定schema路径，Mac用户还需检查符号链接权限及缓存。
GraphQL插件装了但没提示？检查 language-graphql 是否启用
VSCode 默认不带 GraphQL 语言支持，必须靠插件补全。很多人装了 GraphQL（Prisma 官方插件）或 GraphQL for VSCode（kumarharsh）后仍无语法高亮、自动补全，核心原因是：插件只提供能力，不自动关联 .graphql 或 .gql 文件类型——得手动告诉 VSCode “这类文件用 GraphQL 模式解析”。
实操建议：
- 打开 VSCode 设置（
Cmd+,或Ctrl+,），搜files.associations，点击“在 settings.json 中编辑” - 添加以下映射：
"*.graphql": "graphql", "*.gql": "graphql", "schema.graphql": "graphql"
- 重启 VSCode 或用
Ctrl+Shift+P→ 输入Developer: Reload Window刷新 - 确认当前文件右下角显示 “GraphQL” 而非 “Plain Text”
GraphQL 查询校验报错 “Cannot query field on type Query”？检查 graphql-config 是否生效
语法提示能出，但字段名标红、跳转失败、IntelliSense 不识别 schema 字段——大概率是 VSCode 没读到你的 GraphQL Schema。不是插件问题，而是缺少配置让插件知道“你的 schema 长什么样、从哪来”。
实操建议：
- 项目根目录建
graphql.config.yml或graphql.config.js，内容至少包含schema和documents字段 - 如果 schema 来自本地文件（如
schema.graphql），写：schema: ./schema.graphql documents: './src/**/*.{graphql,gql}' - 如果 schema 来自运行中的服务（如
http://localhost:4000/graphql），需加extensions.endpoints并确保服务可访问；注意跨域或鉴权会静默失败 - 插件只认
graphql-configv3+ 格式，旧版.graphqlconfig（JSON）已不被主流插件支持
用 Apollo Client 时 gql 模板字符串没提示？需要 graphql-tag + 类型声明配合
在 JS/TS 文件里写 gql`query GetUser { user(id: $id) { name } }`，VSCode 插件默认不识别这种模板字符串为 GraphQL 片段——它只扫描 .graphql 文件或显式标记的代码块。
实操建议：
- 安装
graphql-tag（npm i -D graphql-tag），并在 TS 项目中配好类型定义：import { gql } from 'graphql-tag'; - 在
jsconfig.json或tsconfig.json的compilerOptions里加："plugins": [{ "name": "@graphql-tools/graphql-tag-pluck" }]（仅限需要自动提取的场景） - 更可靠的做法：用
/* GraphQL */注释显式标记模板字符串，例如：const query = /* GraphQL */ gql`query GetUser { user(id: $id) { name } }`;—— 多数插件（包括GraphQL插件）会识别该注释并激活校验 - 注意：ESLint 或 Prettier 可能误删该注释，建议在 ESLint 配置中禁用
no-unused-vars对注释的检查
Mac 上按 Cmd+Click 跳转 schema 字段失败？重点查 node_modules 权限和缓存
Windows/Linux 用户常能跳转成功，Mac 用户却点不动——不是插件 bug，而是 macOS 对 node_modules 下符号链接（symlink）或只读文件的处理更严格，尤其搭配 pnpm 或 yarn 3 的 .pnp.cjs 时。
实操建议：
- 先运行
npx graphql-inspector introspect http://localhost:4000/graphql --write schema.json，确认 schema 能正常拉取（排除网络/鉴权问题） - 检查插件是否在读取缓存：删除
~/.vscode/extensions/graphql.vscode-graphql-*/out/cache/目录（路径随插件版本变） - 如果用 pnpm，确保
graphql-config中的schema路径不指向node_modules/.pnpm/...内部路径，而应指向 workspace 内的副本或 URL - 跳转依赖 TypeScript 语言服务，务必确认项目已启用
typescript.tsdk设置指向本地node_modules/typescript/lib/tsserverlibrary.js
GraphQL 支持不是装个插件就完事，它本质是“客户端（VSCode）→ 配置（graphql-config）→ 数据源（schema）”三段链路，任一环断开，提示、校验、跳转都会静默失效。最容易被忽略的是配置文件路径是否被 VSCode 正确加载，以及 Mac 下对符号链接的权限限制——别急着换插件，先看输出面板里 GraphQL 频道有没有报 “Failed to load schema” 这类日志。
