ApolloClient 3中混用@client与远程片段失效问题咨询

嘿，我刚碰到过几乎一模一样的问题，这其实是Apollo Client 3搭配graphql-tag/loader时，处理混合远程服务器字段+本地客户端片段查询的一个常见坑，我来给你拆解得明明白白：

核心原因 #

问题出在Apollo对混合查询的解析逻辑和graphql-tag/loader的AST处理上：

• 情况a正常：你用的是带@client标记的单个字段（isLeftSidebarOpen @client），Apollo能轻松识别这个标记，自动把查询拆成「服务器处理部分（me { ...BasicUserInfo }）」和「客户端本地处理部分（isLeftSidebarOpen）」，服务器只会收到自己能理解的内容，所以运行正常。
• 情况b正常：整个查询只有客户端片段，Apollo直接判定这是纯本地操作，不会发送给服务器，完全在客户端解析片段，自然不会触发服务器的片段校验。
• 情况c报错：当你把服务器字段和客户端片段放在同一个查询里时，graphql-tag/loader没有正确将客户端片段的引用从服务器查询部分剥离。哪怕你给片段引用加了@client，Apollo的默认逻辑还是会把包含...IsLeftSidebarOpen的完整查询AST发送给服务器。服务器根本不知道你本地定义的这个片段，于是就抛出了「Unknown fragment "IsLeftSidebarOpen"」的错误。

解决方案 #

这里有几个靠谱的解决办法，按推荐程度排序：

1. 分离服务器查询与客户端查询（最推荐） #

把混合查询拆成两个独立的操作，在组件中同时调用，逻辑清晰且完全避免解析混淆：

# 服务器端查询（仅请求远程数据）
const FETCH_USER_DATA = gql`
  #import '../../hooks/fragments/User/basicUserInfo.gql'
  query FetchUserData {
    me { ...BasicUserInfo }
  }
`;

# 客户端查询（仅获取本地状态）
const FETCH_SIDEBAR_STATE = gql`
  fragment IsLeftSidebarOpen on Query { isLeftSidebarOpen @client }
  query FetchSidebarState {
    ...IsLeftSidebarOpen @client
  }
`;

在组件中使用：

const { data: userData } = useQuery(FETCH_USER_DATA);
const { data: sidebarData } = useQuery(FETCH_SIDEBAR_STATE);

2. 升级graphql-tag/loader并明确标记客户端片段 #

如果你不想拆分查询，可以先升级graphql-tag/loader到最新版本，修复旧版本的解析bug：

npm install graphql-tag/loader@latest

同时给客户端片段的定义和引用都加上@client(only: true)标记，明确告诉Apollo这部分完全不需要和服务器交互：

fragment IsLeftSidebarOpen on Query { 
  isLeftSidebarOpen @client(only: true) 
}

query FetchData {
  me { ...BasicUserInfo }
  ...IsLeftSidebarOpen @client(only: true)
}

3. 调整webpack的graphql-loader配置 #

确保webpack配置中正确处理.gql/.graphql文件，避免loader漏处理片段定义：

module.exports = {
  module: {
    rules: [
      {
        test: /\.(graphql|gql)$/,
        exclude: /node_modules/,
        loader: 'graphql-tag/loader',
        options: {
          // 开启片段合并支持
          mergeImportedFragments: true
        }
      },
    ],
  },
};

总结 #

本质问题就是Apollo在混合查询场景下，没有正确识别客户端片段的作用域，导致不该发给服务器的片段引用被误发送。拆分查询是最稳妥的方案，代码可读性也更高；如果不想拆分，升级loader+明确标记的方式也能解决问题。

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