Next.js 13+ 应用中 not-found.js 未正常渲染 404 页面，常因 Node.js 版本不满足最低要求（v16.14+）导致——升级至 v16.14 或更高版本（如 v18.16.1）即可修复该兼容性问题。
next.js 13+ 应用中 `not-found.js` 未正常渲染 404 页面，常因 node.js 版本不满足最低要求（v16.14+）导致——升级至 v16.14 或更高版本（如 v18.16.1）即可修复该兼容性问题。
在 Next.js App Router 中，not-found.js（或 .tsx）是专用于捕获客户端和服务器端路由失败的特殊文件，应放置于 app/ 目录下（支持嵌套路径，如 app/tickets/[id]/not-found.js），并在数据获取失败时主动调用 notFound() 触发渲染。但实践中，许多开发者遇到该文件完全不生效、页面空白、甚至控制台无报错的情况——这往往并非代码逻辑错误，而是底层运行时兼容性问题。
根本原因：Node.js 版本过低
Next.js v13.4+（尤其是含 App Router 的稳定功能）明确要求 Node.js ≥ 16.14.0。若使用 16.13.2 等旧版本，虽然开发服务器能启动，但部分服务端能力（如 notFound() 的异常拦截与边界重渲染机制）无法正确初始化，导致 not-found.js 被静默忽略，最终返回空响应体（HTTP 200 + 空 HTML），表现为“白屏”。
✅ 验证与修复步骤：
-
检查当前 Node.js 版本：
node --version # 若输出 v16.13.x 或更低，请立即升级
-
升级至受支持版本（推荐 LTS）：
- 使用 nvm（macOS/Linux）：
nvm install 18.16.1 nvm use 18.16.1
- Windows 用户可使用 nvm-windows 或直接下载 Node.js 官方 LTS 安装包。
- 使用 nvm（macOS/Linux）：
-
清理缓存并重启开发服务器：
rm -rf .next npm run dev # 或 yarn dev / pnpm dev
补充说明：确保 not-found.js 正确使用
即使 Node.js 版本合规，也需确认以下实践规范：
- not-found.js 必须是 Client Component（默认行为），不可标记 "use client"，也不应包含服务端逻辑；
- notFound() 必须在服务端组件（Server Component）的数据获取流程中同步调用（如示例中的 getTicket 函数内），不能包裹在 useEffect 或事件处理器中；
- 不要手动抛出错误替代 notFound() —— 后者会触发 Next.js 的专用 404 渲染流，而 throw new Error() 可能降级为全局错误边界（error.js）。
// ✅ 正确示例：app/tickets/[id]/not-found.tsx
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 ticket you requested does not exist.</p>
<a
href="/tickets"
className="mt-4 px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700"
>
← Back to Tickets
</a>
</div>
);
}⚠️ 注意事项：
- Next.js 不会在控制台或终端中主动提示 “Node.js version incompatible with not-found.js” —— 这是已知体验缺陷，需开发者自行对照官方系统要求文档核对；
- 若升级后仍无效，请检查是否误将 not-found.js 放置于 pages/ 目录（App Router 下该目录被忽略），或存在拼写错误（如 notfound.js 缺失连字符）；
- 生产环境部署（Vercel、Docker 等）同样需确保运行时 Node.js 版本 ≥16.14，建议在 package.json 中通过 "engines" 字段声明：
"engines": { "node": ">=16.14.0" }
升级 Node.js 是解决此类“无声失效”问题最高效的方式。保持运行时环境与框架要求严格对齐，是保障 Next.js App Router 高级功能（如 not-found.js、error.js、loading.js）稳定落地的前提。
