React Hooks渲染异常：Rendered fewer hooks问题排查与解决

问题背景 #

开发房源市场展示页面时，通过TRPC获取后端数据，使用TanStack React Table渲染表格，频繁遇到偶发的Rendered fewer hooks than expected错误，常规排查手段无效，怀疑与TRPC query传递给Table组件的方式有关。

相关代码示例（疑似错误写法） #

父组件（传递TRPC数据） #

const PropertyList = () => {
  const { data: properties, isLoading } = trpc.property.getAll.useQuery();

  if (isLoading) return <LoadingSpinner />;

  return <PropertyTable data={properties} />;
};

Table组件（渲染表格） #

const PropertyTable = ({ data }: { data: Property[] }) => {
  // 错误：条件判断提前return，导致后续hooks未执行
  if (!data?.length) return <div>No properties found</div>;

  const columns = useMemo(() => [
    { accessorKey: 'id', header: 'ID' },
    { accessorKey: 'name', header: 'Property Name' },
  ], []);

  const table = useReactTable({
    data,
    columns,
  });

  return (
    <table>
      {/* 表格渲染逻辑 */}
    </table>
  );
};

错误截图 #

排查与解决方案 #

1. 严格遵守React Hooks规则 #

偶发错误核心原因是组件渲染分支导致hooks执行数量不一致：当数据为空或加载状态变化时，Table组件内的条件return跳过了后续hooks调用，违反了"hooks必须在组件顶层执行"的规则。

修改Table组件，确保所有hooks始终在顶层执行：

const PropertyTable = ({ data }: { data: Property[] | undefined }) => {
  // 所有hooks放在组件最顶层，不受数据状态影响
  const columns = useMemo(() => [
    { accessorKey: 'id', header: 'ID' },
    { accessorKey: 'name', header: 'Property Name' },
  ], []);

  const table = useReactTable({
    data: data ?? [], // 空数据时传入默认空数组，避免undefined
    columns,
  });

  // 条件渲染放在hooks执行完成后
  if (!data?.length) return <div>No properties found</div>;

  return (
    <table>
      {/* 表格渲染逻辑 */}
    </table>
  );
};

2. 避免传递完整TRPC Query对象 #

不要将TRPC query返回的整个对象（包含isLoading、error等状态）传给子组件，仅传递所需的data，并在父组件统一处理加载/错误状态：

const PropertyList = () => {
  const { data: properties, isLoading, error } = trpc.property.getAll.useQuery();

  if (isLoading) return <LoadingSpinner />;
  if (error) return <div>加载房源失败：{error.message}</div>;

  return <PropertyTable data={properties ?? []} />;
};

3. 稳定TRPC Query的触发逻辑 #

偶发错误可能与TRPC query的缓存重触发有关，可通过配置staleTime减少不必要的重渲染：

const { data: properties } = trpc.property.getAll.useQuery(
  {},
  { staleTime: 5000 } // 5秒内使用缓存数据，避免频繁重新请求
);

4. 用React DevTools定位问题 #

打开React DevTools的"Hooks"面板，监控Table组件的hooks执行顺序与数量，当错误触发时，对比正常渲染与错误渲染时的hooks执行差异，定位未执行的hooks。

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