Next.js启动遇UNKNOWN错误，删除.next后触发根布局缺失问题求助

问题复盘 #

• 运行npm run dev时随机触发：

  [Error: UNKNOWN: unknown error, readlink '\routes-manifest.json'] {
    type: 'Error', errno: -4094, code: 'UNKNOWN', syscall: 'readlink', path: '\routes-manifest.json'
  }
  

• 删除.next缓存后出现布局错误：*error page.tsx doesn't have a root layout. To fix this error, make sure every page has a root layout.*
• 克隆仓库重新部署正常，推测为运行时修改文件导致缓存冲突。

解决步骤 #

1. 彻底清理缓存与依赖 #

不要仅删除.next，执行完整清理流程：

• macOS/Linux：

  rm -rf .next node_modules package-lock.json yarn.lock
  npm install
  npm run dev
  

• Windows（PowerShell）：

  Remove-Item -Recurse -Force .next, node_modules, package-lock.json, yarn.lock
  npm install
  npm run dev
  

2. 修复根布局文件 #

Next.js 强制要求存在根布局/入口文件，根据你的路由模式检查：

• App Router（app目录）：确保根目录下有app/layout.tsx，且正确导出带children的组件：

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

• Pages Router（pages目录）：确保pages/_app.tsx存在并导出默认App组件：

  import type { AppProps } from 'next/app'
  
  export default function App({ Component, pageProps }: AppProps) {
    return <Component {...pageProps} />
  }
  

3. 避免运行时文件修改的缓存冲突 #

• 运行npm run dev时，停止服务后再新增/修改app/pages目录下的文件，不要在热重载过程中操作
• 若需动态添加页面，可临时修改next.config.js禁用部分缓存逻辑：

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

4. 排查系统级权限与锁定问题 #

• Windows用户尝试用管理员权限打开终端运行项目，解决文件权限不足问题
• 检查.next文件夹是否被杀毒软件、OneDrive等工具锁定，临时关闭此类工具后重试

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