schema地址错误会导致typegen失败，需确保schema可访问且结构完整；推荐用本地.graphql文件，url方式须配headers；documents路径须匹配查询文件，generates路径须以.ts结尾并重启ts server。
schema 地址填错会导致 typegen 全部失败
生成类型前，schema 必须可访问且结构完整。常见错误是填了本地 http://localhost:4000/graphql 但后端没跑，或填了远程 URL 却被 CORS / 认证拦截。VSCode 插件本身不执行 codegen，它依赖 CLI 工具读取 schema —— 所以失败时终端报错通常是 Failed to fetch schema 或 Invalid introspection result。
推荐做法：
- 先手动 curl 测试：
curl -X POST -H "Content-Type: application/json" -d '{"query":"{__schema{types{name}}}"}' http://localhost:4000/graphql - 开发期优先用本地
.graphql文件（如schema.graphql），通过schema: "./src/graphql/schema.graphql"引用，避免网络依赖 - 若必须用 URL，确保配置
headers（比如带Authorization）—— 这要在codegen.ts的schema字段里嵌套写，不是放外面
documents 路径没匹配到 .graphql 文件就啥也不生成
documents 是 codegen 扫描“哪些文件里写了查询”的唯一依据。默认值 ['src/**/*.graphql'] 只抓后缀为 .graphql 的独立文件，但如果你把查询写在 gql 模板字符串里（比如 React 组件中的 const QUERY = gql`...`），这个路径就得加上 src/**/*.tsx，否则类型不会为这些查询生成。
典型配置漏项：
- 用了 Apollo Client 但没加
src/**/*.ts和src/**/*.tsx - 查询分散在多个目录，却只写了
src/queries/*.graphql，漏了src/components/**/* - 路径用了双引号导致 glob 失效（应写单引号或不用引号，TypeScript 配置中推荐单引号）
生成的类型没出现在编辑器里？检查 generates 输出路径和 preset
生成的文件存在磁盘上，不代表 VSCode 能识别为 TypeScript 类型。关键两点：
-
generates目标路径必须以.ts结尾（如./src/generated/graphql.ts），不能是文件夹（如./src/generated/）—— 后者需要配合preset: "client"才能展开成多文件，否则会报错 - 如果用了
preset: "client"，它默认启用typescript+typescript-operations，但不会自动加typescript-react-query或typescript-urql—— 这些得显式声明在plugins里 - 生成后记得运行
tsc --noEmit或重启 TS Server（Ctrl+Shift+P → “Restart TS server”），否则编辑器缓存旧类型
typegen 命令卡住或没反应？先看 package.json 脚本和 node_modules
npx graphql-codegen 不是 VSCode 插件自带的命令，它来自你项目里安装的 @graphql-codegen/cli。常见静默失败原因：
- 全局安装了旧版 CLI（v2.x），但项目用的是 v5.x 配置格式 —— 必须用
npx @graphql-codegen/cli显式指定 -
codegen.ts导出的config类型不对，比如用了CodegenConfig但没从@graphql-codegen/cli导入，TS 编译会跳过校验，CLI 却解析失败 - 脚本写成
"generate": "graphql-codegen"却没在package.json的devDependencies里装 CLI，导致 npm run 时找不到命令
最稳的启动方式：npx @graphql-codegen/cli --config codegen.ts --watch，加 --watch 能实时反馈错误位置。
