Next.js中queryClient.setQueryData更新失效与不一致问题排查

为什么React Query的setQueryData不触发重渲染？ #

React Query触发组件重渲染的核心是检测缓存数据的引用变化，它内部会对新旧数据做浅比较。如果你的performIndicesChange函数是原地修改了existingBoard的数组或对象（比如用splice、push直接修改原数组，或直接修改对象属性），然后把同一个引用传给setQueryData，React Query会判定数据无变化，因此不会通知组件更新。

举个错误示例：

// 错误：原地修改原数组，返回原引用
const performIndicesChange = (board, from, to) => {
  const movedItem = board.lists.splice(from, 1)[0];
  board.lists.splice(to, 0, movedItem);
  return board;
};

这种情况下，setQueryData接收的是同一个对象/数组引用，React Query不会触发重渲染。

为什么未使用的setBoard能生效？ #

调用setBoard会强制触发组件重新渲染，不管board变量是否被用到。组件重渲染时，useFetchBoard会重新读取React Query缓存中的数据——此时虽然缓存的引用没变化，但数据已经被你原地修改过，所以data会是修改后的值，KanbanBoard也就显示了更新后的布局。这是组件重渲染带来的副作用，并非正确的状态更新方式。

正确解决方案 #

1. 保证数据更新是不可变的 #

修改performIndicesChange，返回全新的对象/数组引用，避免原地修改原数据。可以用ES6展开运算符、map实现：

const performIndicesChange = (board, fromIndex, toIndex) => {
  // 复制原lists数组，避免原地修改
  const newLists = [...board.lists];
  // 移动元素
  const [movedItem] = newLists.splice(fromIndex, 1);
  newLists.splice(toIndex, 0, movedItem);
  // 返回全新的board对象
  return {
    ...board,
    lists: newLists
  };
};

如果数据结构复杂，也可以用immer库简化不可变更新，它允许用“可变”写法生成不可变数据：

import { produce } from 'immer';

const performIndicesChange = (board, fromIndex, toIndex) => {
  return produce(board, draft => {
    const [movedItem] = draft.lists.splice(fromIndex, 1);
    draft.lists.splice(toIndex, 0, movedItem);
  });
};

2. 移除无用的useState #

既然board状态未被使用，直接删除const [board, setBoard] = useState<TBoard | null>(null);和setBoard(newBoard)这两行，完全依赖React Query的缓存管理状态。

3. 验证useFetchBoard的封装 #

确保useFetchBoard正确封装了useQuery，没有额外逻辑导致data引用被意外保留：

// 正确的useFetchBoard示例
const useFetchBoard = (queryKey) => {
  return useQuery({
    queryKey,
    queryFn: () => fetch('/api/board').then(res => res.json())
  });
};

修改后，每次拖拽调用setQueryData时，传入的是全新引用，React Query会检测到变化并触发组件重渲染，KanbanBoard就能正确显示更新后的布局。

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