React-Query useMutation点赞UI不更新及页面刷新报错问题

问题1：点击点赞按钮后点赞数未在UI更新 #

核心原因 #

• 缓存未同步更新：点赞是mutation操作，若未在mutation成功后通知Query更新对应缓存，UI会一直读取旧数据。
• 缓存更新逻辑缺失：useMutation未配置onSuccess钩子来触发缓存刷新或直接修改缓存。
• Query Key不匹配：更新缓存时使用的Query Key和获取数据的Query Key不一致，导致无法定位目标缓存。

解决代码示例 #

假设你的文章查询和点赞逻辑如下，调整后可解决问题：

import { useMutation, useQueryClient, useQuery } from '@tanstack/react-query';

// 获取单篇文章的Query（明确Query Key）
const useGetArticle = (articleId: string) => {
  return useQuery({
    queryKey: ['article', articleId],
    queryFn: () => fetch(`/api/articles/${articleId}`).then(res => res.json()),
  });
};

// 点赞Mutation（配置缓存更新逻辑）
const useLikeArticle = (articleId: string) => {
  const queryClient = useQueryClient();
  return useMutation({
    mutationFn: () => fetch(`/api/articles/${articleId}/like`, { method: 'POST' }),
    onSuccess: () => {
      // 方案1：使对应Query失效，触发重新拉取最新数据（适合需要确保数据绝对最新的场景）
      queryClient.invalidateQueries({ queryKey: ['article', articleId] });

      // 方案2：直接修改缓存（无需重新请求，性能更优，适合确定数据变化规则的场景）
      // queryClient.setQueryData(['article', articleId], (oldData) => {
      //   if (!oldData) return oldData;
      //   return { ...oldData, likeCount: oldData.likeCount + 1 };
      // });
    },
  });
};

问题2：页面刷新后控制台报错、页面空白 #

核心原因 #

• QueryClient未全局初始化：刷新后应用未通过QueryClientProvider全局提供QueryClient实例，导致组件无法访问Query上下文。
• Hydration不匹配（SSR场景）：服务端渲染时，客户端与服务端的Query缓存不一致，触发hydration报错。
• 版本兼容问题：React 18与TanStack Query v5版本不匹配，或依赖未正确安装。

解决方法 #

1. 全局配置QueryClient
   在应用入口文件（如main.tsx）中正确初始化并注入QueryClient：

import React from 'react';
import ReactDOM from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import App from './App';

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 按需设置缓存过期时间
      retry: 1,
    },
  },
});

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </React.StrictMode>,
);

2. 处理SSR Hydration不匹配
   若使用Next.js等SSR框架，需等待hydration完成后再发起Query请求：

import { useQuery } from '@tanstack/react-query';
import { useHydration } from 'next/react-query'; // 以Next.js为例

const useGetArticle = (articleId: string) => {
  const { isHydrated } = useHydration();
  return useQuery({
    queryKey: ['article', articleId],
    queryFn: () => fetch(`/api/articles/${articleId}`).then(res => res.json()),
    enabled: isHydrated, // 等待hydration完成后再请求
  });
};

3. 检查版本兼容性
   确保依赖版本匹配，重新安装依赖：

npm uninstall @tanstack/react-query
npm install @tanstack/react-query@latest

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