Next.js v12.3.0中Layout RFC无法正常工作的原因及解决方法

• 路由优先级规则：Next.js 中 Pages Router（pages/ 文件夹）的路由优先级高于 App Router（app/ 文件夹），当项目同时存在两个文件夹时，框架会优先匹配 pages/ 下的路由规则，导致 app/ 内的路由无法被触发。
• 版本兼容性问题：App Router 是 Next.js 13.0.0 及以上版本才引入的特性，若项目使用的版本低于该阈值，app/ 文件夹不会被框架识别，自然无法生效。
• 文件命名不规范：App Router 对文件命名有严格要求，页面组件必须命名为 page.jsx/page.tsx（例如 app/about/page.jsx 对应 /about 路径），如果错误沿用 Pages Router 的命名方式（比如直接创建 app/about.jsx），会导致路由无法匹配。

• 确认并升级 Next.js 版本

  1. 执行以下命令查看当前版本：

     npm list next
     

  2. 若版本低于 13.0.0，执行升级命令：

     npm install next@latest react@latest react-dom@latest
     

  3. 升级完成后重启开发服务器。

• 处理路由冲突

  • 若要完全切换到 App Router：直接删除 pages/ 文件夹（注意迁移必要的全局配置，比如原 pages/_app.js 的全局样式或 Provider 可迁移到 app/layout.jsx，原 pages/_document.js 可迁移到 app/document.jsx）。
  • 若需过渡阶段同时保留两个路由系统（不推荐长期使用）：确保 Next.js 版本在 13.4+（App Router 稳定版），此时框架会自动处理部分共存场景，但需避免定义相同路径的路由（比如不要同时在 pages/about.js 和 app/about/page.jsx 中定义 /about 路由）。

• 修正 App Router 文件命名
  检查 app/ 内的文件结构，确保页面组件遵循命名规范：

  • 根路径对应 app/page.jsx
  • /about 路径对应 app/about/page.jsx
  • 嵌套布局对应 app/layout.jsx 或子文件夹下的 layout.jsx

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