NextJS从Page Router迁移到App Router后构建报错：找不到500.html

问题分析 #

迁移后app/500/page.tsx出现构建ENOENT错误，且访问时UI正常但返回500状态码，核心原因是App Router对错误页面的处理逻辑与Page Router不同，同时可能存在构建缓存或路径配置冲突。

解决方案 #

1. 修正500页面的配置逻辑 #

App Router中两种500相关页面的区别：

• 可访问的/500路由页面：保留app/500/page.tsx，但需明确设置状态码，避免NextJS误识别为错误处理页。
• 全局服务器错误捕获页面：如果不需要单独的/500路由，改用app/error.tsx（必须是客户端组件），自动捕获服务器端错误并返回500状态码。

2. 解决构建ENOENT错误 #

• 清理依赖缓存：

  yarn cache clean && yarn install
  

  或

  npm cache clean --force && npm install
  

• 删除.next和out目录（如果有静态导出产物），重新构建：

  rm -rf .next out && next build
  

• 检查next.config.js，移除exportPathMap这类Page Router专属配置，确保无自定义导出路径与旧路由冲突。

3. 修复/500页面返回500状态码的问题 #

如果保留app/500/page.tsx作为可访问路由，在组件中添加状态码设置：

import { NextResponse } from 'next/server';

// 服务器组件中设置响应状态码
export async function generateMetadata() {
  const response = NextResponse.next();
  response.headers.set('x-status-code', '200');
  return {};
}

export default function Custom500Page() {
  return (
    <div className="container">
      <h1>500 - 服务器错误</h1>
      <p>抱歉，服务器出现了问题，请稍后重试。</p>
    </div>
  );
}

若使用app/error.tsx作为全局错误处理组件，示例代码：

'use client';

import { useEffect } from 'react';

export default function Error({ error, reset }: { error: Error & { digest?: string }, reset: () => void }) {
  useEffect(() => {
    console.error('服务器错误:', error);
  }, [error]);

  return (
    <div className="error-page">
      <h2>出错了！</h2>
      <p>服务器遇到了未知问题，请点击下方按钮重试。</p>
      <button onClick={reset} className="retry-btn">重试</button>
    </div>
  );
}

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