Next.js 14升级后AWS CodeBuild构建报错：Headers is not defined

我使用AWS CodeBuild构建Next.js应用已有多年，一直正常运行。近期将项目从Next.js 13升级到14后，构建失败并出现以下错误：

unhandledRejection ReferenceError: Headers is not defined
    at Object.<anonymous> (/codebuild/output/src3629032198/src/node_modules/next/dist/server/web/spec-extension/adapters/headers.js:32:30)
    at Module._compile (node:internal/modules/cjs/loader:1198:14)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1252:10)
    at Module.load (node:internal/modules/cjs/loader:1076:32)
    at Function.Module._load (node:internal/modules/cjs/loader:911:12)
    at Module.require (node:internal/modules/cjs/loader:1100:19)
    at Module.mod.require (/codebuild/output/src3629032198/src/node_modules/next/dist/server/require-hook.js:64:28)
    at require (node:internal/modules/cjs/helpers:119:18)
    at Object.<anonymous> (/codebuild/output/src3629032198/src/node_modules/next/dist/server/api-utils/index.js:63:18)
    at Module._compile (node:internal/modules/cjs/loader:1198:14)

该错误来自Next.js代码库本身，我自己的代码中并未引用过"Headers"。

相关配置信息 #

package.json构建脚本 #

"build": "NEXT_PUBLIC_VERSION=$npm_package_version NEXT_PUBLIC_DATE=$(date +%s) next build",

buildspec.yml #

version: 0.2
phases:
  pre_build:
    commands:
      - npm install
  build:
    commands:
      - npm run build
artifacts:
  files:
    - '**/*'
  base-directory: build

next.config.js #

const isLocal = process.env.NODE_ENV === 'development';

const nextConfig = {
  trailingSlash: true,

  // Build settings
  output: 'export',
  distDir: 'build',

  // Handle SVG imports
  webpack(config) {
    config.module.rules.push({
      test: /\.svg$/i,
      issuer: /\.[jt]sx?$/,
      use: '@svgr/webpack',
    });
    return config;
  },

  // SCSS options
  sassOptions: {
    logger: {
      warn: function (message) {
        console.warn(message);
      },
      debug: function (message) {
        console.log(message);
      },
    },
  },

  // Define whether to remove console.log statements from the deployed code
  compiler: {
    removeConsole: isLocal ? false : true,
  },
};

module.exports = nextConfig;

版本升级说明 #

使用Next.js 13时，构建脚本末尾包含&& next export -o build：

"build": "NEXT_PUBLIC_VERSION=$npm_package_version NEXT_PUBLIC_DATE=$(date +%s) next build && next export -o build",

升级到14后，按照官方指南将配置移至next.config.js：

output: 'export',
distDir: 'build',

解决方案 #

1. 升级AWS CodeBuild的Node.js版本 #

Next.js 14要求Node.js版本至少为18.17.0或更高。旧版本Node（如16.x）不支持全局Headers对象，这是报错的核心原因。

修改buildspec.yml，在pre_build阶段指定Node版本：

version: 0.2
phases:
  pre_build:
    commands:
      - nvm install 18.17.0
      - nvm use 18.17.0
      - npm install
  build:
    commands:
      - npm run build
artifacts:
  files:
    - '**/*'
  base-directory: build

如果你的CodeBuild镜像未预装nvm，可直接使用支持Node.js 18+的官方镜像，例如aws/codebuild/amazonlinux2-x86_64-standard:5.0。

2. 清理依赖缓存 #

旧的依赖缓存可能导致版本冲突，在pre_build阶段添加清理命令：

pre_build:
  commands:
    - rm -rf node_modules package-lock.json
    - nvm install 18.17.0
    - nvm use 18.17.0
    - npm install

3. 确认静态导出配置无误 #

当前next.config.js中的output: 'export'和distDir: 'build'配置符合Next.js 14的要求，无需额外执行next export命令，确保没有其他配置干扰静态导出流程。

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