AWS Amplify에서 Next.js SSR 앱이 깨지는 이유 (그리고 런타임 환경 변수 해결법)

Next.js App Router + SSR 앱을 Vercel에서 AWS Amplify로 이전할 때, 겉으로 보기에는 모든 게 정상처럼 보일 수 있습니다.

• 빌드는 성공하고
• 환경 변수도 설정되어 있고
• IAM 권한도 다 맞춰놨는데

막상 배포하고 나면 앱이 런타임에서 500 에러와 함께 죽습니다. 로그를 보면 항상 같은 메시지죠.

“환경 변수가 없습니다”

저도 Cognito + API Gateway + Lambda + RDS를 사용하는 실제 프로덕션 앱을 옮기면서 이 문제를 그대로 겪었습니다.

이 글에서는:

• 왜 이런 문제가 발생하는지
• Amplify에서 실제로 동작하는 해결 방법은 무엇인지

를 정리합니다.

근본 원인: Amplify의 빌드 타임 vs 런타임 환경 변수 차이

AWS Amplify Web Compute(SSR) 에서 환경 변수는 Vercel과 동작 방식이 다릅니다.

Vercel에서는 잘 되는 이유

Vercel에서는 환경 변수가:

• 빌드 타임
• 런타임 (SSR, route handler, server component)

모두에서 자동으로 주입됩니다.

그래서 어디서든:

process.env.MY_VAR

가 “그냥” 잘 동작합니다.

Amplify에서는 무슨 일이 벌어질까?

Amplify는 다릅니다.

• 빌드 타임에는 환경 변수를 주입해 줍니다
• 하지만 SSR 런타임(Compute 환경) 에는 자동으로 전달되지 않습니다

결과적으로:

• ✅ 빌드는 성공
• ❌ SSR 런타임에서 크래시
• ❌ route handler에서 process.env.MY_VAR === undefined

이 현상은 버그가 아니라 설계된 동작입니다.

AWS 문서에도 나오지만, Vercel에 익숙하면 거의 100% 놓치게 되는 포인트입니다.

흔히 보이는 증상들

대부분 아래와 같이 나타납니다.

• 모든 페이지에서 500 에러

• 로그에:

  • 환경 변수가 한꺼번에 전부 없음
  • 또는 AWS SDK 호출 시 CredentialsProviderError

• 로컬과 Vercel에서는 정상

• Amplify에서만 실패

제대로 동작하는 해결 방법

1️⃣ 비밀 값은 AWS Secrets Manager로 이동

Cognito client secret 같은 민감한 값은:

• AWS Secrets Manager에 저장
• Amplify의 Compute role에 아래 권한 부여:

secretsmanager:GetSecretValue

이렇게 하면 런타임 환경 변수 주입에 의존하지 않아도 됩니다.

2️⃣ 런타임 환경 변수를 빌드 시점에 굽기(bake)

API URL, redirect URI 같은 비밀이 아닌 값은 Amplify 권장 방식이 따로 있습니다.

👉 빌드 중에 .env.production 파일을 직접 생성하는 방식입니다.

amplify.yml 예시:

build:
  commands:
    - env | grep '^COGNITO_' >> .env.production
    - env | grep '^REPORTS_API_BASE_URL' >> .env.production
    - pnpm build

이렇게 하면:

• Amplify의 빌드 환경
• Next.js SSR 런타임 기대치

사이의 간극을 메울 수 있습니다.

3️⃣ 서버 사이드 설정 코드 점검 (중요)

Secrets Manager로 옮긴 뒤에는 서버 코드에서 NEXT_PUBLIC_*를 참조하면 안 됩니다.

❌ Amplify에서 깨지는 패턴:

process.env.NEXT_PUBLIC_SOMETHING

✅ 올바른 패턴:

process.env.SOMETHING

정리하면:

• NEXT_PUBLIC_* → 브라우저 / 클라이언트 전용

• 서버에서는:

  • 비밀 값 → Secrets Manager
  • 일반 값 → .env.production으로 주입된 env

왜 Amplify에서만 깨질까?

• Vercel은 SSR 런타임에 env vars를 자동 주입

• Amplify는:

  • 빌드 환경
  • 컴퓨트 런타임

을 명확히 분리함

• Next.js는 런타임 env가 있다고 가정
• Amplify에서는 그 연결을 직접 만들어줘야 함

이걸 알고 나면, 해결 자체는 어렵지 않습니다.

TL;DR

Amplify에서 Next.js SSR 앱이 깨진다면:

1. 비밀 값 → AWS Secrets Manager
2. 런타임 env → 빌드 중 .env.production에 기록
3. 서버 코드에서 NEXT_PUBLIC_* 사용 금지
4. Logging role 말고 Compute role 권한 확인

이렇게 하면 Amplify SSR도 안정적으로 동작합니다.

아래는 의미를 정확히 유지한 한글 번역이야. 경고성은 살리고, 기술 문서 톤으로 정리했어.

IAM Role 관련 주의사항 (놓치기 쉬운 포인트)

AWS Amplify는 서로 다른 두 개의 IAM Role을 사용하며, 이 둘을 혼동하면 SSR 앱이 조용히(silent) 깨질 수 있습니다.

• Service role

  • Amplify 자체가 사용하는 역할
  • 빌드, 배포, 로그 수집 용도
  • 앱 서버 코드에는 사용되지 않음

• Compute role

  • Next.js SSR 런타임에서 서버 코드가 실행될 때 Assume 되는 역할

런타임에서 AWS 서비스(예: Secrets Manager)에 접근하려면 반드시 Compute role을 앱에 지정해야 합니다.

이를 설정하지 않으면:

• SSR 런타임에는 AWS 자격 증명이 전혀 없고
• 그 결과 CredentialsProviderError 같은 오류가 발생합니다.

Compute role에는 서버 코드에 실제로 필요한 최소 권한만 부여해야 합니다 (예: secretsmanager:GetSecretValue).

이 역할은 로그/빌드용 Service role과 완전히 별개이며, Amplify 콘솔에서 명시적으로 설정해야만 적용됩니다.