Next13 App Router中not-found.tsx报错及产品适用性咨询

一、先抓准错误核心 #

先把浏览器控制台的具体错误信息（比如 hydration 失败、资源加载报错、组件渲染异常）复制出来，这是解决问题的关键。以下是几种高频场景的处理方案：

1. Hydration 不匹配（最常见） #

如果报错是Hydration failed because the initial UI does not match what was rendered on the server这类：

• 检查你的not-found.tsx，如果用到了window、document这类仅客户端可用的API，必须在文件最顶部加上'use client'指令——App Router默认是服务器组件，不能直接用客户端API。
• 修正示例：

'use client'; // 必须放在文件第一行

export default function NotFound() {
  return (
    <div className="p-8">
      <h1>404 - 页面不存在</h1>
    </div>
  );
}

• 另外，组件里的条件渲染要避免服务端和客户端不一致，比如用typeof window !== 'undefined'包裹客户端专属逻辑，防止服务端渲染时出现差异。

2. Turbo 模式下的缓存冲突 #

用next dev --turbo启动时出现大量错误，基本是Turbo的缓存机制搞的鬼：

• 先清缓存再重启：

rm -rf .next && next dev --turbo

• 要是还不行，暂时给not-found.tsx排除缓存：

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  turbo: {
    cacheKey: {
      exclude: ['not-found.tsx'],
    },
  },
};

module.exports = nextConfig;

3. 版本或依赖兼容问题 #

• 确认你用的是Next.js稳定版，别用canary尝鲜版，执行npm list next看版本，直接更到最新稳定版：

npm install next@latest

• 检查项目里的UI组件库、工具库是否和当前Next.js版本兼容，部分旧库在App Router下会有渲染异常。

二、关于Next.js生产可用性的疑问 #

作为4年React SPA经验的开发者，觉得不适应太正常了——Next.js不是“SPA增强版”，它是全栈框架，核心是SSR/SSG这些服务端能力，和纯SPA的开发思路完全不同：

• 生产环境下Next.js的稳定性是经过大厂验证的，Vercel、Netflix、Twitch这些公司都在大规模用。
• App Router是13+的新特性，初期确实有坑，但现在已经迭代到稳定阶段，只要跟着官方规范写，不会有生产风险。
• 建议先放下SPA的固有思路，从“路由的服务端渲染逻辑”入手，先搞懂服务器组件/客户端组件的区别，这是适应Next.js的关键。

三、额外排查点 #

• 确认not-found.tsx的位置：App Router中，全局404要放在app/not-found.tsx，子路由的404要放在对应路由段的根目录（比如app/blog/not-found.tsx对应blog路由下的404），放错位置会导致异常。
• 检查next.config.js的trailingSlash配置，如果开了trailingSlash: true，/404和/404/会有路由匹配差异，可能引发报错。

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