应装graphql for vscode和es7+ react/redux/react-native snippets；禁用已废弃的graphql language service；需配置.graphqlrc指定schema路径并手动重载；typescript中须全局声明gql函数类型；提示错误时需检查schema与运行环境是否一致。
GraphQL插件装哪些才不踩坑
VSCode官方市场里叫“GraphQL”的插件有十几个，但真正能用的只有两个：一个是GraphQL for VSCode（由Prisma团队维护），另一个是ES7+ React/Redux/React-Native snippets（顺带补全gql模板字符串）。别装GraphQL Language Service——它已废弃，和最新版VSCode冲突，装了反而导致.graphql文件无法高亮、无自动补全。
安装后重启VSCode，再打开一个.graphql文件，如果看到字段名带灰色下划线、悬停提示类型，说明服务已就绪；否则检查是否误启用了其他冲突插件。
schema.json怎么自动加载进VSCode
VSCode的GraphQL插件不会自动读取项目里的schema，必须显式配置路径。常见错误是把schema.json放在src/下却没告诉插件——它默认只查根目录或.graphqlrc指定位置。
在项目根目录新建.graphqlrc，内容如下：
{
"schema": "./schema.json",
"documents": ["src/**/*.{ts,tsx,js,jsx}"]
}
注意两点：
• schema路径必须是相对.graphqlrc的，不能写成src/schema.json（除非.graphqlrc也在src里）
• 如果用的是introspection.json，文件名要同步改，插件不认schema.graphql这种SDL格式，除非额外加extensions配置
• 修改后需右键任意.graphql文件 → “Reload GraphQL Schema”，不能靠重启生效
在TypeScript里写gql模板字符串没提示？
插件默认只识别gql`...`和graphql`...`两种前缀，但很多人用import { gql } from 'graphql-tag'或@apollo/client，这时候必须手动声明tag函数类型，否则VSCode根本不知道这是GraphQL片段。
在项目里加一个graphql.d.ts（放在src/@types或根目录types下）：
declare module 'graphql-tag' {
export function gql(literals: TemplateStringsArray, ...placeholders: any[]): any;
}
或者更稳妥的方式（适配Apollo Client v3+）：
import { TypedDocumentNode } from '@apollo/client';
declare global {
namespace GraphQLTag {
export interface DocumentNode<t any v="any"> extends TypedDocumentNode<t v> {}
}
}
declare function gql(literals: TemplateStringsArray, ...placeholders: any[]): GraphQLTag.DocumentNode;</t></t>
关键点：
• 必须是declare function gql，不能写成const gql
• 如果用ESM且报错“Cannot find name 'gql'”，检查tsconfig.json里"typeRoots"是否包含该.d.ts路径
• gql必须是全局声明，放组件文件里无效
IntelliSense提示字段但报“Cannot query field”？
这是最典型的“schema和运行时不一致”问题：VSCode根据本地schema.json做提示，但后端实际返回的schema可能已更新（比如新增字段未重新导出），或当前环境连的是测试/预发接口，而你加载的是生产schema。
验证步骤：
• 运行npx get-graphql-schema http://localhost:4000/graphql -j > schema.json（替换成你的endpoint）重新生成
• 检查schema.json里是否有对应字段（搜索字段名，看是否在__type里）
• 如果用的是Apollo Federation，确认schema.json是聚合后的supergraph，不是单个subgraph的schema
• 插件不支持动态schema刷新，每次后端变更都得手动重载
容易被忽略的一点：某些BFF层会根据请求头（如X-Env: staging）返回不同schema，但VSCode加载的只是静态文件——它没法模拟header，所以开发时务必确认手动生成schema.json用的是目标环境地址。
