Next.js 13.4.13 AWS Amplify重部署预渲染/500页面报错求助

问题概述 #

• 使用Next.js 13.4.13版本，采用app路由构建Web应用，部署到AWS Amplify平台
• 首次部署应用运行正常，但修改代码后重新部署时出现预渲染错误：

  [WARNING]: Error occurred prerendering page "/500". Read more: https://nextjs.org/docs/messages/prerender-error TypeError: Cannot read properties of null (reading 'useContext')
  

• 未自定义错误页面，代码中仅使用useState，未引入useContext
• 删除现有Amplify应用并重新创建部署，可恢复正常运行
• 本地执行pnpm build无任何/500或/404页面预渲染错误，本地构建输出如下：

  Route (app)                                Size     First Load JS
  ─ ○ /                                      56.3 kB         135 kB
  + First Load JS shared by all              78.3 kB
    ├ chunks/291-c577ad0e930e9c15.js         25.9 kB
    ├ chunks/2bece34a-8484c688a7ebdb4e.js    50.5 kB
    ├ chunks/main-app-60fd3ca2e8e14587.js    211 B
    └ chunks/webpack-d7bc6ccbc9bf2471.js     1.67 kB
  
  Route (pages)                              Size     First Load JS
  ─ ○ /404                                   182 B          75.7 kB
  + First Load JS shared by all              75.5 kB
    ├ chunks/framework-510ec8ffd65e1d01.js   45 kB
    ├ chunks/main-ded02ef5ae1b734f.js        28.6 kB
    ├ chunks/pages/_app-e3a45f45b4fcedf8.js  196 B
    └ chunks/webpack-d7bc6ccbc9bf2471.js     1.67 kB
  
  ○  (Static)  automatically rendered as static HTML (uses no initial props)
  

应用目录结构 #

app
├── globals.css
├── layout.tsx
└── page.tsx

核心代码片段 #

page.tsx #

import Company from "@/sections/Company";
import {
  Mission,
  Services,
  Team,
  Hero,
  Navbar,
  Details,
  Footer,
} from "../sections";

const Page = () => (
  <div className="bg-primary-black overflow-hidden">
    <Navbar />
    <Hero />
    <div className="relative">
      <Mission />
      <div className="gradient-03"></div>
      <Details />
      <div className="gradient-04"></div>
      <Services />
      <div className="gradient-06"></div>
    </div>
    <div className="relative">
      <div className="gradient-left"></div>
      <Team />
      <div className="gradient-right"></div>
      <Company />
    </div>
    <Footer />
  </div>
);

export default Page;

layout.tsx #

import "./globals.css";
import type { Metadata } from "next";
import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Linknit",
  description: "Linknit: Link your every need for a study abroad",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <link rel="icon" href="linknit-logo.svg" />
      <body>
        <main>{children}</main>
      </body>
    </html>
  );
}

排查方向与解决方案 #

1. Amplify构建缓存残留 #

二次部署时Amplify可能保留了旧的构建缓存（比如pages路由残留文件、依赖缓存），导致app路由与旧pages路由逻辑冲突，触发默认/500页面预渲染时出错。本地构建是干净环境，因此无此问题。

• 解决：
  • 手动在Amplify控制台的构建页面点击「清除缓存并重新构建」
  • 在Amplify构建设置的preBuild阶段添加清理命令：

    preBuild:
      commands:
        - rm -rf .next node_modules
        - npm install -g pnpm
        - pnpm install
    

2. 默认错误页面路由冲突 #

本地构建显示存在pages/404页面，Amplify部署时可能触发了Next.js旧pages路由的默认错误页面逻辑，导致预渲染/500时调用了不存在的Context。

• 解决：在app目录下创建自定义错误页面，覆盖默认逻辑：
  • 创建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="container mx-auto p-4">
          <h2>出现错误，请稍后重试</h2>
          <button onClick={reset} className="mt-4 px-4 py-2 bg-blue-500 text-white rounded">
            重新加载
          </button>
        </div>
      );
    }
    

  • 创建app/not-found.tsx：

    export default function NotFound() {
      return (
        <div className="container mx-auto p-4">
          <h2>页面不存在</h2>
        </div>
      );
    }
    

3. 依赖管理工具不一致 #

本地使用pnpm，Amplify默认可能用npm/yarn，导致依赖安装版本不一致，触发React运行时错误。

• 解决：在Amplify构建设置中指定使用pnpm，修改buildSpec：

  version: 1
  frontend:
    phases:
      preBuild:
        commands:
          - npm install -g pnpm@latest
          - pnpm install
      build:
        commands:
          - pnpm build
    artifacts:
      baseDirectory: .next
      files:
        - '**/*'
    cache:
      paths:
        - node_modules/**/*
        - .pnpm-store/**/*
  

4. 构建模式差异 #

本地与Amplify的构建模式可能不一致（比如本地静态导出，Amplify启用SSR），导致预渲染逻辑不同。

• 解决：检查next.config.js配置，确保本地与Amplify构建模式一致，例如如果是静态站点，添加：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    output: 'export',
  }
  
  module.exports = nextConfig;
  

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