Next.js动态导入组件中useRouter报NextRouter未挂载错误排查

1. 为何设置{ssr: false}仍出现NextRouter was not mounted错误？ #

常见触发原因包括：

• 路由钩子导入错误：Next.js 13+的App Router与Pages Router使用不同的useRouterAPI——前者从next/navigation导入，后者从next/router导入。导错路径会直接导致钩子无法获取客户端路由实例。
• 违反React钩子规则：useRouter是React钩子，必须在组件函数的顶层作用域调用，不能放在条件判断、循环、嵌套函数或useEffect内部，否则哪怕是客户端组件也会报错。
• 组件被SSR路径意外引用：即便设置了{ssr: false}，如果组件被_app.js（Pages Router）、未加'use client'的layout（App Router）等SSR必执行的文件直接/间接引用，Next.js可能在SSR阶段解析组件代码，触发钩子调用。
• 旧版本Next.js bug：部分早期版本的dynamic配置{ssr: false}存在逻辑漏洞，导致组件仍会在SSR阶段执行部分代码。

2. 动态导入组件中使用useRouter的注意事项与最佳实践 #

• 区分Router环境：
  • Pages Router：使用next/router的useRouter，动态导入必须添加{ssr: false}。
  • App Router：优先用'use client'标记客户端组件（替代dynamic {ssr: false}），同时导入next/navigation的useRouter。
• 严格遵守钩子规则：useRouter必须在组件函数顶层调用，禁止在条件逻辑、嵌套函数内使用。
• 避免SSR环境触发钩子：
  • Pages Router：动态导入的组件不要在_app.js、_document.js等SSR必执行文件中直接引用。
  • App Router：所有使用useRouter的组件必须标记'use client'，且不能在服务器组件中渲染。
• 延迟获取路由参数（可选）：若存在初始化时机问题，可通过useEffect延迟获取参数，确保路由实例已挂载：

  const EventRouterComponent = () => {
    const router = useRouter();
    const [eventId, setEventId] = useState(null);
  
    useEffect(() => {
      const eventId = router.query.event_id || new URLSearchParams(window.location.search).get('event_id');
      if (eventId) setEventId(eventId);
    }, [router.query]);
  
    // 后续逻辑
  };
  

3. 该问题与Next.js路由/上下文机制的关联及解决方案 #

这个问题本质是路由实例挂载时机与组件渲染时机不匹配：

• Pages Router中，路由实例仅在客户端浏览器环境下存在，SSR阶段无路由实例；若动态导入组件在SSR阶段被解析，调用useRouter就会报错。
• App Router中，服务器组件默认无权限访问客户端路由上下文，必须标记为客户端组件才能获取路由实例。

具体解决方案： #

方案1：修正钩子导入与组件标记

• Pages Router场景：
  确保组件导入正确的useRouter，动态导入代码无误：

  // page.js (Pages Router)
  import dynamic from 'next/dynamic';
  
  const EventRouterComponent = dynamic(
    () => import('../components/EventRouterComponent'),
    { ssr: false }
  );
  
  export default function EventPage() {
    return <EventRouterComponent />;
  }
  

  组件内部正确调用钩子：

  // EventRouterComponent.js
  import { useRouter } from 'next/router';
  import { useContext } from 'react';
  import { EventIdContext } from '../contexts/EventIdContext';
  
  export default function EventRouterComponent() {
    const router = useRouter();
    const { setEventId } = useContext(EventIdContext);
    
    // 仅在客户端处理路由参数
    if (typeof window !== 'undefined' && router.query.event_id) {
      setEventId(router.query.event_id);
    }
  
    return null; // 仅负责同步路由参数到上下文，无需渲染内容
  }
  

• App Router场景：
  给组件添加'use client'指令，导入正确的路由钩子：

  // EventRouterComponent.js (App Router)
  'use client';
  
  import { useRouter } from 'next/navigation';
  import { useContext, useEffect } from 'react';
  import { EventIdContext } from '../contexts/EventIdContext';
  
  export default function EventRouterComponent() {
    const router = useRouter();
    const { setEventId } = useContext(EventIdContext);
  
    useEffect(() => {
      const params = new URLSearchParams(window.location.search);
      const eventId = params.get('event_id');
      if (eventId) setEventId(eventId);
    }, [router, setEventId]);
  
    return null;
  }
  

  页面中直接导入组件（无需dynamic，'use client'已标记为客户端组件）：

  // page.js (App Router)
  import EventRouterComponent from '../components/EventRouterComponent';
  import { EventIdContextProvider } from '../contexts/EventIdContext';
  
  export default function EventPage() {
    return (
      <EventIdContextProvider>
        <EventRouterComponent />
        {/* 其他子组件 */}
      </EventIdContextProvider>
    );
  }
  

方案2：调整上下文提供者层级

将EventIdContextProvider放在路由实例已挂载的层级：

• Pages Router：放在_app.js中，确保上下文在客户端路由初始化后生效。
• App Router：给EventIdContextProvider添加'use client'指令，放在页面或客户端layout中，避免在服务器组件中渲染。

方案3：客户端环境前置检查

在组件中先判断是否为客户端环境，再执行路由相关逻辑：

import { useRouter } from 'next/router';

export default function EventRouterComponent() {
  if (typeof window === 'undefined') {
    return null; // SSR阶段不执行逻辑
  }
  
  const router = useRouter();
  // 后续逻辑
}

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