Apollo-Client缓存更新报错及组件未重渲染问题排查

你遇到的核心问题是缓存修改没有匹配组件查询的完整缓存条目（包含查询变量），同时缺少对totalCount字段的更新，导致React没有检测到数据变化。以下是具体修复步骤：

关键问题分析 #

1. 查询变量匹配：FileUploads查询带有offset/first等变量，Apollo会将变量作为缓存键的一部分。直接修改fileUploads字段只会更新无变量的缓存条目，而组件实际订阅的是带默认变量的缓存条目，所以不会触发重渲染。
2. totalCount未更新：原查询返回了totalCount，新增文件后该值未同步更新，React可能因数据未发生“实质性变化”而跳过重渲染。
3. 缓存ID生成：手动拼接FileUpload:${file.id}虽然解决了报错，但不如使用Apollo内置的cache.identify可靠，它会自动遵循缓存的ID生成规则（适配Postgraphile的类型命名）。

修复代码示例（推荐使用cache.modify+查询ID） #

update(cache, { data }) {
  const newFiles = data?.uploadToService?.result || [];
  if (newFiles.length === 0) return;

  // 生成组件查询对应的缓存键（必须匹配组件使用的变量）
  const queryCacheKey = cache.identify({
    query: FileUploadsDocument, // codegen生成的查询文档
    variables: { 
      offset: 0, 
      first: 10, 
      orderBy: ['CREATED_AT_DESC'] 
    }
  });

  cache.modify({
    id: queryCacheKey,
    fields: {
      fileUploads(existing = { nodes: [], totalCount: 0 }) {
        // 为新文件生成缓存引用并写入缓存
        const newFileRefs = newFiles.map(file => {
          cache.writeFragment({
            id: cache.identify(file), // 自动生成正确的缓存ID
            data: file,
            fragment: gql`
              fragment NewFileUpload on FileUpload {
                id
                uploaderOrgId
                uploadFileType
                counterPartiesCount
                parsedPointsCount
                effectiveDate
                originalFileName
                configFileName
                createdAt
                status
                uploadingOrg { id shortName }
                entitiesAndCps { entities { id shortName } cps { id shortName } }
              }
            `
          });
          return cache.identify(file);
        });

        // 返回完整的查询结构，包含更新后的nodes和totalCount
        return {
          ...existing,
          nodes: [...newFileRefs, ...existing.nodes],
          totalCount: existing.totalCount + newFiles.length
        };
      }
    }
  });
}

替代方案：使用readQuery+writeQuery #

如果觉得cache.modify不够直观，可以直接读写指定查询的缓存：

update(cache, { data }) {
  const newFiles = data?.uploadToService?.result || [];
  if (newFiles.length === 0) return;

  // 读取组件当前查询的缓存数据
  const existingData = cache.readQuery({
    query: FileUploadsDocument,
    variables: { offset: 0, first: 10, orderBy: ['CREATED_AT_DESC'] }
  });

  if (!existingData) return;

  // 将新文件写入缓存
  newFiles.forEach(file => {
    cache.writeFragment({
      id: cache.identify(file),
      data: file,
      fragment: gql`
        fragment NewFile on FileUpload {
          id
          uploaderOrgId
          uploadFileType
          counterPartiesCount
          parsedPointsCount
          effectiveDate
          originalFileName
          configFileName
          createdAt
          status
          uploadingOrg { id shortName }
          entitiesAndCps { entities { id shortName } cps { id shortName } }
        }
      `
    });
  });

  // 写入更新后的查询数据到缓存
  cache.writeQuery({
    query: FileUploadsDocument,
    variables: { offset: 0, first: 10, orderBy: ['CREATED_AT_DESC'] },
    data: {
      fileUploads: {
        ...existingData.fileUploads,
        nodes: [...newFiles, ...existingData.fileUploads.nodes],
        totalCount: existingData.fileUploads.totalCount + newFiles.length
      }
    }
  });
}

额外注意事项 #

• 如果组件支持分页（不同的offset/first变量），需要遍历所有相关的缓存条目进行更新，或者在用户切换分页时重新拉取数据。
• 确保FileUploadsDocument是codegen生成的正确查询文档，避免手动拼写查询导致的缓存键不匹配。

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