AWS Amplify Gen2 SSR运行时环境变量缺失导致未定义错误

核心问题本质 #

你的流水线虽然生成了.env.production并复制到.next目录，但Amplify的SSR运行时不会自动读取该文件中的变量。Next.js在Amplify SSR环境下，必须通过Amplify控制台的环境变量配置直接注入运行时变量，仅靠构建时生成的.env文件无法满足需求。

分步解决方案 #

1. 配置Amplify控制台环境变量 #

• 登录AWS Amplify控制台，进入目标应用 → 环境变量页面
• 添加所有需要的变量：
  • 非NEXT_PUBLIC_开头的服务器端变量（如AUTH_SECRET、NEXTAUTH_URL）直接添加，Amplify会自动注入到SSR运行时
  • NEXT_PUBLIC_开头的客户端变量也可在此配置，构建时会自动嵌入客户端代码

2. 优化流水线配置 #

保留构建时生成.env.production的步骤（用于构建阶段变量注入），但可以去掉复制.env.production到.next的冗余步骤，因为Amplify SSR不读取该文件：

version: 1
frontend:
 phases:
   preBuild:
     commands:
    - nvm install 22
    - nvm use 22
    - npm ci
build:
  commands:
    - |
      echo "[INFO] Writing environment variables into .env.production"
      cat << EOF > .env.production
      AUTH_SECRET=$AUTH_SECRET
      NEXTAUTH_URL=$NEXTAUTH_URL
      COGNITO_AUTH_DOMAIN=$COGNITO_AUTH_DOMAIN
      COGNITO_CLIENT_ID=$COGNITO_CLIENT_ID
      COGNITO_CLIENT_SECRET=$COGNITO_CLIENT_SECRET
      COGNITO_ISSUER=$COGNITO_ISSUER
      ACCESS_KEY_ID=$ACCESS_KEY_ID
      SECRET_ACCESS_KEY=$SECRET_ACCESS_KEY
      REGION=$REGION
      NEXT_PUBLIC_API_BASE_URL=$NEXT_PUBLIC_API_BASE_URL
      NEXT_PUBLIC_ENV=$NEXT_PUBLIC_ENV
      NEXT_PUBLIC_ROOT_DOMAIN=$NEXT_PUBLIC_ROOT_DOMAIN
      NEXT_PUBLIC_S3_BUCKET_NAME=$NEXT_PUBLIC_S3_BUCKET_NAME
      NEXT_PUBLIC_S3_BUCKET_REGION=$NEXT_PUBLIC_S3_BUCKET_REGION
      EOF
    - echo "[INFO] Verifying .env.production file:"
    - cat .env.production
    - npm run build
 artifacts:
   baseDirectory: .next
   files:
    - '**/*'
cache:
  paths:
    - node_modules/**/*
    - .next/cache/**/*

3. 确保代码变量读取逻辑正确 #

• Zod验证逻辑需直接读取process.env变量，示例代码：

import { z } from "zod";

const envSchema = z.object({
  AUTH_SECRET: z.string(),
  NEXTAUTH_URL: z.string(),
  // 其他变量定义...
});

export const env = envSchema.parse(process.env);

4. 验证运行时变量注入 #

部署后，在SSR页面或API路由中添加调试代码，确认变量是否已注入：

// 在SSR组件或API路由中添加
console.log("SSR Runtime ENV Check:", {
  AUTH_SECRET: process.env.AUTH_SECRET ? "已加载" : "undefined",
  NEXTAUTH_URL: process.env.NEXTAUTH_URL ? "已加载" : "undefined",
});

关键差异说明 #

Amplify SSR运行环境与Vercel不同：Vercel会自动读取.env.production并注入运行时，但Amplify仅会将控制台配置的环境变量注入到SSR进程，构建时生成的.env文件不会被运行时读取。

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