如何导入特定GraphQL片段？规避未使用片段报错

你当前的文件结构如下：
file.gql：

#import "./fragment.gql"

query Query {
   ...Fragment
}

fragment.gql：

fragment Fragment {
   ...
}
...other fragments here

这种导入方式会因为文件中存在未使用的片段而报错，相关解决方案如下：

核心结论 #

大部分GraphQL工具链不支持单独导入单个片段，默认的导入逻辑是引入整个文件的所有内容，因此只要文件内有未被使用的片段，就会触发“未使用片段”的报错。

可行解决方案 #

• 拆分片段到独立文件：这是最规范的解决方案。把你需要的Fragment单独移到一个新文件（比如target-fragment.gql），然后在file.gql中导入这个新文件：

  #import "./target-fragment.gql"
  
  query Query {
     ...Fragment
  }
  

  这种方式从根源上避免了冗余片段，也符合GraphQL模块化的最佳实践。

• 禁用未使用片段的报错规则：如果你暂时不想拆分文件，可以调整你的GraphQL工具配置，关闭“未使用片段”的检查。比如：

  • 若使用ESLint的eslint-plugin-graphql，可以在.eslintrc中修改规则：

    {
      "rules": {
        "graphql/no-unused-fragments": "off"
      }
    }
    

  • 若使用GraphQL Code Generator，可以在配置文件中添加ignoreNoDocuments: true选项。
    注意：这种方式会关闭所有未使用片段的检查，可能会掩盖真正的冗余代码问题，需谨慎使用。

• 工具扩展语法（不推荐）：少数工具（如部分版本的Apollo Client）支持非标准的导入语法来筛选片段，但这不属于GraphQL官方规范，兼容性差，不建议在项目中依赖这种方式。

针对大规模片段场景的建议 #

如果遇到需要从包含多个片段的文件中使用大部分片段的场景，最佳实践是按业务逻辑或关联度拆分片段文件，把功能相关的片段放在同一个文件中，这样导入时就能自然覆盖所需的片段，减少冗余。

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