Next.js中NavButton组件Hooks调用顺序异常警告排查求助

问题 #

在Next.js中编写了NavButton组件，仅在顶层调用useRouter Hook，但收到React的Hooks调用顺序变更警告，提示前后渲染时useContext的调用出现差异。

组件代码如下：

import Link from "next/link";
import {useRouter} from "next/router";
import clsx from "clsx";

const NavButton = ({icon, 'icon-active': iconActive, title, link, badge, refreshable = false}) => {
    const {pathname, reload} = useRouter();
    const isActive = link === pathname;
    const Icon = isActive ? iconActive : icon;
    const handleRefreshIfRequired = e => {
        if (!refreshable) return;
        if (isActive) {
            e.preventDefault();
            reload();
        }
    };
    return <Link href={link}
                 onClick={handleRefreshIfRequired}
                 className={clsx('home-page-button', {'home-page-button-active': isActive})}>
        <div className="button-icon">
            <Icon/>
        </div>
        <div className="button-title">
            {title}
            {badge && <strong
                className={'bg-danger card text-white px-1 border-none ms-1 font-bold animate-fade inline-block'}>{badge}</strong>}
        </div>
    </Link>;
};

警告信息：

Warning: React has detected a change in the order of Hooks called by NavButton. This will lead to bugs and errors if not fixed. For more information, read the Rules of Hooks: https://reactjs.org/link/rules-of-hooks

   Previous render            Next render
   ------------------------------------------------------
1. useContext                 useContext
2. undefined                  useContext
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

排查分析与解决 #

问题原因 #

你的组件只显式调用了useRouter，但useRouter内部依赖useContext。警告的核心原因来自动态切换的Icon组件：当isActive状态变化时，你在icon和iconActive两个组件间切换，如果这两个组件的Hooks调用情况不一致（比如一个用了useContext另一个没用到，或者两者调用Hooks的数量、顺序不同），就会触发这个警告。

举个常见场景：icon是纯SVG元素或无Hooks的简单组件，但iconActive是自定义函数组件，内部调用了useContext——这会导致组件激活时多了一次useContext调用，非激活时没有，直接破坏了React要求的Hooks调用顺序稳定性。

解决方法 #

1. 统一图标组件的Hooks逻辑：检查icon和iconActive的实现，确保两者的Hooks调用数量、顺序完全一致。如果其中一个不需要某个Hook，可重构逻辑让结构对齐，避免差异。
2. 用条件渲染替代组件切换：不要直接切换组件类型，而是在同一个容器组件内部通过props控制显示状态。示例：

   // 重构图标容器组件
   const NavIcon = ({isActive, defaultIcon, activeIcon}) => {
       // 统一内部逻辑，避免Hooks差异
       return isActive ? activeIcon : defaultIcon;
   };
   
   // 在NavButton中替换原Icon调用
   <div className="button-icon">
       <NavIcon isActive={isActive} defaultIcon={icon} activeIcon={iconActive} />
   </div>
   

3. 对齐组件类型：确保icon和iconActive都是同类型的组件（比如都是函数组件），如果其中一个是类组件或纯DOM元素，会增加Hooks调用差异的概率，尽量统一为函数组件并遵循Hooks规则。

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