迁移至AWS ECS的Next.js应用无法加载环境变量与凭证

一、ECS环境变量运行时无法读取的问题 #

问题根源 #

你当前通过构建阶段将环境变量写入.env.production的方式，会把构建时的变量固化到镜像中，完全忽略了ECS任务定义中配置的运行时环境变量。Next.js的SSR/API路由依赖运行时变量，静态生成的内容也会因为构建时变量导致无法动态更新，这种方案显然不符合部署灵活性要求。

修复步骤 #

1. 删除构建阶段的.env生成命令
   从Dockerfile的builder阶段移除RUN printenv > .env.production，避免构建时变量覆盖运行时变量。

2. 确保Next.js运行时能读取容器环境变量

   • 客户端暴露变量（NEXT_PUBLIC_前缀）：Next.js会自动从运行时环境变量中读取并注入到客户端代码，无需额外配置。
   • 服务端专用变量（无NEXT_PUBLIC_前缀）：Next.js的standalone模式下，server.js会自动加载容器的环境变量，只要ECS任务定义中配置了这些变量，API路由/SSR代码就能直接通过process.env.XXX访问。

3. 正确配置ECS任务定义的环境变量
   在ECS任务定义的容器配置中，直接添加所需的环境变量（或通过AWS Secrets Manager/Parameter Store引用敏感变量），确保容器启动时这些变量已存在。

二、ECS角色凭证无法加载的问题 #

问题根源 #

报错Could not load credentials from any providers说明：

• ECS任务未配置有效的任务角色（Task Role），或角色权限不足；
• 容器无法访问ECS元数据服务获取角色凭证；
• 应用代码未使用AWS SDK的默认凭证链。

修复步骤 #

1. 配置ECS任务角色
   在ECS任务定义中指定任务角色（注意区分任务执行角色）：

   • 任务角色是给应用代码使用的，需要赋予调用目标AWS服务的权限（比如S3:GetObject、DynamoDB:Scan等）；
   • 任务执行角色仅用于ECS拉取镜像、推送日志等操作，和应用的AWS服务调用权限无关。

2. 确保容器能访问ECS元数据服务

   • Fargate模式：默认允许容器访问元数据服务，无需额外配置；
   • EC2模式：确保容器网络模式为awsvpc（推荐），或EC2实例的IAM角色允许访问ECS元数据端点。

3. 验证AWS SDK的使用方式
   应用代码中不要硬编码AWS凭证，直接使用SDK的默认客户端，示例：

   import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
   
   // 自动从ECS任务角色获取凭证，无需手动配置access key/secret
   const s3Client = new S3Client({});
   
   async function getFileFromS3(bucket, key) {
     const command = new GetObjectCommand({ Bucket: bucket, Key: key });
     const response = await s3Client.send(command);
     return response.Body;
   }
   

4. 调试凭证获取情况
   可以在容器中执行以下命令验证元数据服务是否可访问：

   # 替换为你的任务角色ARN
   curl http://169.254.170.2/v2/credentials/arn:aws:iam::123456789012:role/your-ecs-task-role
   

   如果返回有效凭证，说明角色配置正常；如果返回403，检查任务角色的信任关系是否允许ECS服务承担该角色。

调整后的Dockerfile #

FROM node:18-alpine AS base

FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
  if [ -f package-lock.json ]; then npm ci; \
  elif [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f pnpm-lock.yaml ]; then yarn global add pnpm && pnpm i --frozen-lockfile; \
  else echo "Lockfile not found." && exit 1; \
  fi

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ARG NODE_ENV
ENV NODE_ENV=${NODE_ENV}
ENV NEXT_TELEMETRY_DISABLED 1

# 移除构建时生成.env.production的命令
RUN npm run build

FROM base AS runner
WORKDIR /app

RUN apk add --no-cache curl

ENV NODE_ENV production
ENV NEXT_TELEMETRY_DISABLED 1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

RUN mkdir .next
RUN chown nextjs:nodejs .next

# 保留standalone模式的文件拷贝
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000
ENV PORT 3000

CMD ["node", "server.js"]

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