Next.js14平行路由拦截路由报错：initialTree is undefined

核心排查方向 #

• 路由文件结构合法性检查
  平行路由@modal的目录结构必须严格匹配目标路由层级。确认@modal下是否对应创建了admin/dashboard/customers/[customerId]/page.js（或.tsx），且父级目录结构和主路由完全一致。层级缺失或路径不匹配会导致Router无法正确解析初始路由树。
• 默认页（default.js）的正确性
  确保@modal/default.js存在且返回有效的React组件（比如返回null或空占位组件），不能返回undefined或未导出组件。Next.js要求平行路由必须有默认页，否则初始化时会丢失路由树节点。
• 布局组件中平行路由的渲染方式
  检查Dashboard布局中是否正确渲染@modal插槽，必须通过props传递的插槽组件渲染，不能遗漏或硬编码。示例：

  // Dashboard布局示例
  export default function DashboardLayout({ children, modal }) {
    return (
      <div className="dashboard-container">
        {children}
        {modal} {/* 必须渲染平行路由插槽 */}
      </div>
    )
  }
  

• 动态路由参数的传递与解析
  确认列表条目跳转时，是否正确传递customerId参数，且目标页面[customerId]/page.js中正确通过params.customerId获取参数。参数传递错误会导致路由解析失败，触发initialTree异常。
• 客户端路由跳转的方式
  必须使用Next.js的Link组件或useRouter钩子进行客户端跳转，禁止使用原生window.location.href。示例：

  import Link from 'next/link';
  
  <Link href={`/admin/dashboard/customers/${customer.id}`}>
    查看客户详情
  </Link>
  

  原生跳转会绕过Next.js路由初始化逻辑，导致平行路由初始树未正确构建。

常见修复方案 #

1. 复刻路由层级
   对照主路由admin/dashboard/customers/[customerId]/，完全复刻@modal下的目录结构，确保每个层级的文件夹和文件名完全一致。
2. 修复默认页组件
   修改@modal/default.js返回有效组件：

   // @modal/default.js
   export default function ModalDefault() {
     return null; // 或空的<div></div>
   }
   

3. 修正布局插槽渲染
   确保布局组件中正确接收并渲染平行路由的插槽，App Router中平行路由的插槽名对应props.modal，注意拼写不能出错。
4. 清除缓存重启服务
   执行npm run dev --clear-cache（或yarn/pnpm对应命令）后重启开发服务器，清除旧路由配置缓存，确保新配置被重新解析。

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