本地生成比远程 schema 更可靠，因避免网络、鉴权及服务未就绪导致的 graphql-codegen 启动失败；通过 node 脚本按需触发生成，可控性强且兼容 ci；需显式安装 graphql peer dependency 并确保 codegen.ts 中 documents 路径正确、vscode 缓存刷新、生成目录未被 .gitignore 排除。
为什么本地生成比远程 schema 更可靠
远程 schema（比如 https://api.example.com/graphql）在开发阶段容易因网络、鉴权或服务未就绪而失败，导致 graphql-codegen 启动卡住或生成空类型。本地 schema.graphql 文件可直接读取，启动快、无依赖、可 git 跟踪，适合 CI/CD 和离线开发。
如何用 Node 脚本触发实时生成（非 watch 模式）
不依赖 graphql-codegen --watch 的常驻进程，而是通过 Node 脚本按需执行，更可控、易调试、兼容 CI 环境。
- 确保已安装
@graphql-codegen/cli为 devDependency，且项目根目录有codegen.ts - 新建
scripts/generate-types.js，内容如下：
const { codegen } = require('@graphql-codegen/cli');
const path = require('path');
codegen({
config: path.resolve(__dirname, '../codegen.ts'),
silent: true,
}).catch(console.error);
- 在
package.json中添加脚本："gen:types": "node scripts/generate-types.js" - 运行
yarn gen:types或npm run gen:types即可生成，无额外进程占用内存
常见报错：Cannot find module 'graphql' 或 'graphql/language/parser'
这是 @graphql-codegen 运行时对 graphql 包的 peer dependency 要求未满足。它不会自动安装，必须显式声明。
- 执行
yarn add graphql --dev（或npm install graphql --save-dev） - 注意版本匹配：当前稳定版推荐
graphql@16.9.0，@graphql-codegen/*v5.x 系列与之兼容 - 若使用 pnpm，需加
--peer标志或检查pnpm.overrides是否覆盖了graphql版本
生成后类型文件路径混乱或未更新
根源通常是 codegen.ts 中 documents 路径未匹配实际 .graphql 文件位置，或 VSCode 缓存未刷新。
-
documents必须用 glob 模式，例如['src/**/*.graphql', 'src/**/queries/*.ts']，不能写成src/queries/*.graphql（缺少递归） - 生成后，VSCode 可能仍引用旧类型缓存：按
Ctrl+Shift+P→ 输入Developer: Reload Window强制重载 - 检查生成目录是否被
.gitignore排除——若被忽略，TypeScript 会跳过该目录下的类型声明
真正关键的不是“能不能生成”，而是生成的类型是否被 TypeScript 编译器实际识别；路径、glob、缓存、peer dep 四者缺一不可。
