GraphQL Codegen配置使用Glob表达式无法加载文档的问题如何解决？

核心问题定位 #

该匹配失效问题本质是@graphql-codegen/cli 1.20.x版本的两个已知问题叠加导致，和文件路径配置、服务端schema连接能力无关：

• 该版本对documents字段的类型判断存在逻辑偏差：当documents配置为单字符串形式时，内部会跳过glob通配符解析逻辑，直接把字符串当成精确路径查找文件，不会展开**递归匹配规则
• 1.20.1版本未锁定传递依赖globby的小版本，近期依赖更新时，传递安装的globby版本从v11漂移到v12，该版本修改了通配符解析规则，进一步放大了上述逻辑bug

这也解释了逐文件列路径的数组配置能正常运行的原因：这种写法完全绕开了通配符解析流程，直接按传入的精确路径逐文件读取，不受解析逻辑bug影响。

可落地的修复方案 #

• 零成本快速适配：把documents字段从单字符串改为数组形式，保留原有通配符规则即可正常匹配：

  documents:
    - "src/graphql/**/*.graphql"
  

  数组形式的配置会触发正确的glob解析逻辑，自动递归匹配所有子目录下的.graphql文件，无需逐行罗列所有文件路径。
• 如果改数组形式后仍无法匹配，检查两个边界场景：
  • 确认src/graphql目录下没有需要匹配的隐藏文件夹（比如以.开头的fragments、mutations子目录）：新版globby默认不扫描隐藏目录下的文件，这类场景需要在通配符中添加隐藏路径标识
  • 确认执行生成脚本时的工作目录为项目根目录，避免相对路径错位，可在路径前添加根目录标识强化定位：

    documents:
      - "<rootDir>/src/graphql/**/*.graphql"
    

• 长期稳定修复：如果希望恢复单字符串配置的可用性，可以在package.json中通过依赖版本锁定，将globby固定在和当前codegen版本兼容的11.1.0版本（npm项目用overrides字段、yarn项目用resolutions字段配置），重新安装依赖后原有单字符串通配符配置即可恢复正常匹配能力。

临时验证方法：可在项目根目录新建测试脚本，调用和codegen同版本的globby模块，传入通配符路径查看实际扫到的文件列表，快速确认是路径问题还是依赖解析逻辑问题。

内容的提问来源于stack exchange，提问作者GGrassiant