React Query无限查询调用setQueryData无法更新缓存的问题排查

你的setQueryData手动更新缓存无效的核心问题是没有严格遵循不可变更新规则，同时需要确认查询键的一致性。

问题分析 #

你代码里的firstPage.messages.unshift(message)是直接修改原缓存数组的可变操作——虽然之后拷贝了firstPage对象，但messages数组还是原缓存的引用。React Query依赖不可变数据来检测缓存变化，这种嵌套的可变修改会导致缓存更新不被正确识别：即使缓存订阅触发了事件，组件也可能因为数据引用未改变而不重渲染。

修正后的代码 #

将可变操作替换为完全不可变的更新方式：

function useManuallyAddMessage() {
  const queryClient = useQueryClient();

  const manuallyAddMessage = React.useCallback(
    (message: Message) => {
      queryClient.setQueryData<InfiniteData<MessagePage>>(
        [messagesCacheKey, { conversationId: message.conversationId }],
        oldData => {
          if (!oldData) return undefined;

          const [firstPage, ...rest] = oldData.pages;
          // 生成新的messages数组和page对象，避免修改原缓存
          const updatedFirstPage = {
            ...firstPage,
            messages: [message, ...firstPage.messages]
          };

          return {
            ...oldData,
            pages: [updatedFirstPage, ...rest]
          };
        },
      );
    },
    [queryClient],
  );

  return { manuallyAddMessage };
}

额外排查点 #

• 查询键必须完全匹配：检查useInfiniteQuery使用的查询键，是否和setQueryData中的键完全一致（比如是否遗漏分页参数、排序条件等）。键不匹配会导致setQueryData找不到对应的缓存条目。
• 确认组件订阅正常：消费组件的useInfiniteQuery是否使用了相同的查询键，且未设置enabled: false等阻止订阅的配置。
• 验证数据结构一致性：确保MessagePage的类型定义和缓存中实际存储的数据结构完全匹配，比如messages字段是否为数组类型，没有层级错误。

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