Next.js not-found.js 页面空白问题的解决方案-js教程-PHP中文网

Next.js not-found.js 页面空白问题的解决方案

Next.js 13+ App Router 中 not-found.js 不生效导致 404 路由显示空白页，通常由 Node.js 版本不兼容引发——需确保使用 Node.js v16.14 或更高版本（推荐 v18.16+），低版本将静默失效路由错误处理机制。

next.js 13+ app router 中 `not-found.js` 不生效导致 404 路由显示空白页，通常由 node.js 版本不兼容引发——需确保使用 node.js v16.14 或更高版本（推荐 v18.16+），低版本将静默失效路由错误处理机制。

在 Next.js 的 App Router 模式下，not-found.js（或 .tsx）是官方支持的自定义 404 页面机制：只要在任意路由层级（如 app/not-found.js 或 app/tickets/[id]/not-found.js）放置该文件，当 notFound() 被调用或子路由匹配失败时，Next.js 将自动渲染它。但实践中，许多开发者遇到页面完全空白、控制台无报错、网络请求也未触发 not-found.js 渲染的情况——这并非代码逻辑错误，而极可能是运行时环境不满足最低要求。

根本原因：Node.js 版本不达标

Next.js v13.4+ 明确要求 Node.js ≥ v16.14（官方文档系统要求）。若使用 v16.13.2 等旧版本，notFound() 的服务端中断机制无法被正确识别，导致：

notFound() 调用后无跳转、无渲染、无错误日志；
页面停留在 loading 状态或直接白屏；
浏览器 DevTools Network 面板中看不到 not-found.js 的资源加载；
开发服务器（next dev）与生产构建均表现一致，且不会抛出任何警告或错误提示。

✅ 正确做法：升级 Node.js
使用 nvm（macOS/Linux）或 nvm-windows（Windows）快速切换版本：
# 查看当前版本
node -v  # 输出类似 v16.13.2 → 需升级

# 安装并启用推荐版本（如 v18.16.1）
nvm install 18.16.1
nvm use 18.16.1

# 验证
node -v  # 应输出 v18.16.1
npm run dev  # 重启开发服务器

补充验证：确保 not-found.js 实现规范

虽然版本是主因，但请同步检查文件是否符合约定：

Aria2 Json Rpc

通过 JSON‑RPC 2.0 与 aria2 下载管理器交互，使用自然语言命令管理下载、查询状态并控制任务。适用于 aria2、下载管理或种子操作。

下载

// app/not-found.tsx （推荐使用 TSX，支持 JSX 语法）
'use client' // ⚠️ 注意：not-found 组件必须标记为 Client Component

export default function NotFound() {
  return (
    <div classname="flex flex-col items-center justify-center min-h-screen p-4">
      <h1 classname="text-3xl font-bold text-red-600">404 — Page Not Found</h1>
      <p classname="mt-2 text-gray-600">The requested resource does not exist.</p>
      <button onclick="{()"> window.history.back()}
        className="mt-4 px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
      >
        Go Back
      </button>
    </div>
  )
}

⚠️ 关键注意事项：

not-found.js/tsx 必须位于 app/ 目录下（支持嵌套，如 app/products/not-found.tsx 仅对 /products/* 下无效路径生效）；
文件内无需导出 generateStaticParams 或 dynamic = 'force-dynamic' 等配置；
若用于动态路由（如 app/tickets/[id]/page.tsx），应在数据获取失败时显式调用 notFound()（如你代码所示），且该调用必须在 Server Component 中执行（你的 getTicket 是合法的异步 Server Action）；
not-found 组件本身需加 'use client' —— 这是 Next.js 13.4+ 的强制要求，否则可能触发 hydration 错误。