Next.js 14.1.0部署AWS Elastic Beanstalk生产环境500错误排查

问题背景 #

Next.js（v14.1.0）应用部署在AWS Elastic Beanstalk，通过AWS CodeBuild的buildspec.yml自动化部署。此前运行正常，近期未修改应用代码或环境配置，Chrome控制台出现500内部错误，仅生产构建存在该问题。

浏览器访问部署URL时触发错误，服务器web.stdout.log日志显示TypeError（如C is not a function、s is not a function），提示Server Components渲染失败。

异常现象 #

• API路由（如https://example.com/api/health）可正常返回数据
• app目录下的页面路由（如https://example.com/login）访问失败

版本信息 #

• nextjs: 14.1.0
• react/react-dom: 18.2.0
• node: 18.18.2
• npm: 9.8.1

已尝试的排查步骤 #

• 下载CodeBuild生成的问题构建包，本地执行npm run start仍出现相同错误
• 回滚至应用旧版本，错误依旧
• 本地生成生产构建包并运行，无异常
• 确认本地、CodeBuild及Elastic Beanstalk环境的Node.js、npm版本一致

生产构建配置（buildspec.yml） #

version: 0.2

cache:
  paths:
    - 'node_modules/**/*' # Cache `node_modules` for faster `yarn` or `npm i`
    - '.next/cache/**/*' # Cache Next.js for faster application rebuilds

phases:
  install:
    on-failure: ABORT 
    # runtime-versions:
    #   nodejs: 18.18.x
    commands:
      # Installing the same version on the ElasticBeanStalk instance  
      - n 18.18.2
      - node --version
      - npm --version
      - npm install
  build:
    on-failure: ABORT
    commands:
      - node --version
      - npm run build
  post_build:
    on-failure: ABORT
    commands:
      # Copying only the files we need to the dist folder because 
      # that is used as our base directory for the artifact
      - mkdir dist/
      - cp -r .next dist/
      - cp -r .ebextensions dist/
      - cp package.json Procfile .env.production dist/

artifacts:
  files:
    - '**/*'
  base-directory: dist

解决步骤 #

1. 清理CodeBuild缓存 #

缓存的node_modules或.next/cache文件可能损坏或版本不兼容，是此类问题的常见根源。修改buildspec.yml，在install阶段强制清理缓存：

phases:
  install:
    on-failure: ABORT 
    commands:
      - n 18.18.2
      - node --version
      - npm --version
      - rm -rf node_modules .next/cache # 强制清理旧缓存
      - npm install

重新触发CodeBuild构建并部署，验证是否解决问题。若有效，后续可保留缓存，但定期清理或在依赖更新时强制清理。

2. 校验环境变量一致性 #

本地与CodeBuild的环境变量差异可能导致构建产物异常。在build阶段添加命令打印环境变量文件内容，对比差异：

build:
  on-failure: ABORT
  commands:
    - node --version
    - cat .env.production # 打印环境变量文件内容
    - npm run build

确认.env.production文件内容完整，且CodeBuild环境无额外变量覆盖配置。

3. 检查构建产物完整性 #

CodeBuild生成的.next文件夹可能存在文件缺失。在post_build阶段添加命令检查页面构建产物：

post_build:
  on-failure: ABORT
  commands:
    - mkdir dist/
    - cp -r .next dist/
    - cp -r .ebextensions dist/
    - cp package.json Procfile .env.production dist/
    - ls -la dist/.next/server/app/login # 检查登录页面构建产物是否存在

若文件缺失，排查CodeBuild磁盘空间是否充足，或尝试npm install --force解决依赖安装问题。

4. 验证Elastic Beanstalk运行环境 #

登录Elastic Beanstalk实例，执行node --version和npm --version确认版本与配置一致；检查/var/log/nodejs/nodejs.log获取更多报错细节。同时确认Procfile配置正确（如web: npm run start），启动命令与本地一致。

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