Next.js13开发环境下点击拦截路由触发HotReload更新Router报错

问题背景 #

使用Next.js 13拦截路由+并行路由实现模态框时，开发环境（npm run dev）点击链接会触发客户端异常，控制台报错：Cannot update a component ('HotReload') while rendering a different component ('Router')，生产环境运行正常。

可行解决方案 #

• 升级Next.js到最新稳定版
  这个报错是Next.js开发环境的已知问题，官方在后续版本中已修复。执行以下命令更新依赖：

  npm install next@latest
  # 或使用yarn
  yarn add next@latest
  

• 检查模态框组件的状态更新逻辑
  如果你的@modal/(.)person/[id]/page.tsx里存在渲染阶段直接调用setState的代码（比如组件顶层同步执行状态更新、非回调/非useEffect内的状态修改），会触发该异常。确保所有状态更新都放在事件回调、useEffect或者状态更新函数中。

• 临时禁用快速刷新（仅作排查用）
  若暂时无法升级版本，可在next.config.js中关闭开发环境的快速刷新功能（会降低开发效率，不建议长期使用）：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    fastRefresh: false,
  }
  
  module.exports = nextConfig
  

问题原因 #

这个异常是开发环境独有的HotReload（快速刷新）机制与路由组件的状态更新逻辑冲突导致的：当触发拦截路由的客户端跳转时，HotReload组件会在Router组件渲染过程中触发状态更新，违反了React“渲染阶段不能更新其他组件状态”的规则。生产环境没有HotReload机制，因此不会出现该问题。

额外检查点 #

确认你的路由配置和链接逻辑正确：

1. 根layout.tsx中需包含@modal并行路由插槽，示例：

   export default function RootLayout({
     children,
     modal,
   }: {
     children: React.ReactNode
     modal: React.ReactNode
   }) {
     return (
       <html lang="zh-CN">
         <body>
           {children}
           {modal}
         </body>
       </html>
     )
   }
   

2. Person组件中的链接需正确指向目标路由：

   import Link from "next/link";
   
   function Person({ id, name }: PersonData) {
     return (
       <Link href={`/person/${id}`}>
         <div className="p-4 border rounded">{name}</div>
       </Link>
     );
   }
   

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