AWS AppRunner构建阶段无法读取Next.js的.env环境变量问题

问题背景 #

从Elastic Beanstalk迁移至AWS App Runner后，Next.js项目在App Runner的构建阶段无法读取环境变量。本地执行npm run build正常，Elastic Beanstalk通过GitHub Actions注入变量构建也正常，但App Runner UI配置的环境变量仅在启动阶段可用，构建阶段无法访问。

可行解决方案 #

1. 配置App Runner构建阶段专用环境变量 #

AWS App Runner区分构建时环境变量和运行时环境变量，UI中默认配置的是运行时变量，需单独配置构建时变量：

• 控制台操作：在App Runner服务配置的「构建」步骤中，添加「构建时环境变量」，填入需要在next build阶段使用的变量。
• 使用apprunner.yaml配置：在build区块下的environment字段定义构建所需变量，示例：

version: 1.0
runtime: nodejs18
build:
  commands:
    - npm install
    - npm run build
  environment:
    # 构建阶段需要的环境变量
    NEXT_PUBLIC_API_URL: "your-api-endpoint"
    NEXT_PUBLIC_STANDARD_PRICE_ID: "your-stripe-price-id"
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: "your-stripe-key"
run:
  command: npm start
  environment:
    # 运行阶段需要的变量（可选）

注意：使用apprunner.yaml后，UI中配置的变量会被覆盖，敏感变量建议通过AWS Secrets Manager或Parameter Store引用，示例：

environment:
  NEXT_PUBLIC_API_URL: "{{resolve:secretsmanager:marketbase/web/api-url:SecretString:NEXT_PUBLIC_API_URL}}"

2. 沿用GitHub Actions提前构建，再部署到App Runner #

复用原Elastic Beanstalk的构建流程，在GitHub Actions中完成构建后，将产物部署到App Runner：

1. 在GitHub Actions中注入环境变量并执行npm run build
2. 打包构建产物（.next、public、package.json等核心文件）
3. 配置App Runner直接使用已构建的代码，跳过构建步骤（启动命令设为npm start）

3. 在构建阶段生成.env文件 #

Next.js会自动读取.env.production文件，可在App Runner构建命令前手动生成该文件，将构建变量写入：

build:
  commands:
    # 生成.env.production文件
    - echo "NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL" > .env.production
    - echo "NEXT_PUBLIC_STANDARD_PRICE_ID=$NEXT_PUBLIC_STANDARD_PRICE_ID" >> .env.production
    - echo "NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=$NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY" >> .env.production
    - npm install
    - npm run build

验证步骤 #

• 在构建命令中添加echo $NEXT_PUBLIC_API_URL，查看App Runner构建日志确认变量是否正常读取
• 部署后在页面中输出process.env.NEXT_PUBLIC_API_URL，验证构建产物是否包含正确的变量值

内容的提问来源于stack exchange，提问作者S.B.