일반적인 Amplify 문제 해결 - AWS Amplify 호스팅
HTTP 429 상태 코드(요청이 너무 많음)Amplify 콘솔에 내 앱의 빌드 상태와 마지막 업데이트 시간이 표시되지 않음새로운 pull 요청에 대해 웹 미리 보기가 생성되지 않음Amplify 콘솔에서 수동 배포가 보류 중 상태에서 멈춰 있음내 애플리케이션의 Node.js 버전을 업데이트해야 함

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

일반적인 Amplify 문제 해결

다음 정보는 Amplify Hosting과 관련된 문제를 해결하는 데 도움이 될 수 있습니다.

HTTP 429 상태 코드(요청이 너무 많음)

Amplify는 수신 요청이 사용하는 처리 시간 및 데이터 전송을 기반으로 웹 사이트에 대한 초당 요청 수(RPS)를 제어합니다. 애플리케이션이 HTTP 429 상태 코드를 반환하면 수신 요청이 애플리케이션에 할당된 처리 시간 및 데이터 전송을 초과하는 것입니다. 이 애플리케이션 제한은 Amplify의 REQUEST_TOKENS_PER_SECOND 서비스 할당량에 의해 관리됩니다. 할당량에 대한 자세한 내용은 Amplify Hosting 서비스 할당량 섹션을 참조하세요.

이 문제를 해결하려면 애플리케이션을 최적화하여 요청 지속 시간을 줄이고 데이터 전송량을 줄여 앱의 RPS를 늘리는 것이 좋습니다. 예를 들어 토큰이 20,000개로 동일한 경우 100밀리초 이내에 응답하는 고도로 최적화된 SSR 페이지는 지연 시간이 200밀리초보다 긴 페이지와 비교하여 더 높은 RPS를 지원할 수 있습니다.

마찬가지로 1MB 응답 크기를 반환하는 애플리케이션은 250KB 응답 크기를 반환하는 애플리케이션보다 더 많은 토큰을 사용합니다.

또한 주어진 응답이 캐시에 유지되는 시간을 최대화하는 Cache-Control 헤더를 구성하여 Amazon CloudFront 캐시를 활용하는 것이 좋습니다. CloudFront 캐시에서 제공되는 요청은 속도 제한에 포함되지 않습니다. 각 CloudFront 배포는 초당 최대 250,000개의 요청을 처리할 수 있으므로 캐시를 사용하여 앱의 규모를 크게 조정할 수 있습니다. CloudFront 캐시에 대한 자세한 내용은 Amazon CloudFront 개발자 가이드의 캐싱 및 가용성 최적화를 참조하세요.

Amplify 콘솔에 내 앱의 빌드 상태와 마지막 업데이트 시간이 표시되지 않음

Amplify 콘솔에서 모든 앱 페이지로 이동하면 현재 리전에 있는 각 앱에 대한 타일이 표시됩니다. 특정 앱에 배포됨과 같은 빌드 상태나 마지막 업데이트 시간이 표시되지 않는 경우, 해당 앱에는 Production 단계로 지정된 브랜치가 연결되어 있지 않은 것입니다.

콘솔에서 앱 목록을 표시할 때 Amplify는 ListApps API를 사용합니다. Amplify는 빌드 상태를 표시하기 위해 ProductionBranch.status 속성을, 마지막 업데이트 시간을 표시하기 위해 ProductionBranch.lastDeployTime 속성을 사용합니다. 이 API에 대한 자세한 내용은 Amplify Hosting API 설명서의 ProductionBranch를 참조하세요.

앱의 브랜치에 Production 단계를 연결하려면 다음 지침을 따릅니다.

  1. Amazon 콘솔에 로그인합니다.

  2. 모든 앱 페이지에서 업데이트하려는 앱을 선택합니다.

  3. 탐색 창에서 앱 설정, 브랜치 설정을 차례로 선택합니다.

  4. 브랜치 설정 섹션에서 편집을 선택합니다.

  5. 프로덕션 브랜치에서 프로덕션으로 사용할 브랜치 이름을 선택합니다.

  6. 저장을 선택합니다.

  7. 모든 앱 페이지로 돌아갑니다. 이제 해당 앱의 빌드 상태와 마지막 업데이트 시간이 표시됩니다.

새로운 pull 요청에 대해 웹 미리 보기가 생성되지 않음

웹 미리 보기 기능을 사용하면 pull 요청의 변경 사항을 통합 브랜치에 병합하기 전에 미리 확인할 수 있습니다. 웹 미리 보기는 리포지토리에 생성된 각 pull 요청을 메인 사이트 URL과 다른 고유한 미리 보기 URL에 배포합니다.

앱에서 웹 미리 보기를 활성화했지만 새로운 PR(pull 요청)에 대해 생성되지 않는 경우, 아래 원인 중 하나를 확인해 보세요.

  1. 앱이 Branches per app 서비스 할당량 최대치에 도달했는지 확인합니다. 할당량에 대한 자세한 내용은 Amplify Hosting 서비스 할당량 섹션을 참조하세요.

    앱의 브랜치가 기본 할당량 50개를 초과하지 않도록 자동 브랜치 삭제 기능을 활성화하는 것을 고려하세요. 이 기능은 리포지토리에서 더 이상 존재하지 않는 브랜치가 계정에 누적되는 것을 방지합니다.

  2. 퍼블릭 GitHub 리포지토리를 사용 중이며 Amplify 앱에 IAM 서비스 역할이 연결되어 있는 경우, 보안상의 이유로 웹 미리 보기가 생성되지 않습니다. 예를 들어 백엔드가 있는 앱과 WEB_COMPUTE 호스팅 플랫폼에 배포된 앱에는 IAM 서비스 역할이 필요합니다. 따라서 리포지토리가 퍼블릭인 경우 이러한 유형의 앱에 대해 웹 미리 보기를 활성화할 수 없습니다.

    웹 미리 보기를 앱에서 사용 가능하게 하려면, 서비스 역할 연결을 해제하거나(앱에 백엔드가 없거나 WEB_COMPUTE 앱이 아닌 경우) GitHub 리포지토리를 비공개로 전환합니다.

Amplify 콘솔에서 수동 배포가 보류 중 상태에서 멈춰 있음

수동 배포를 사용하면 Git 공급자를 연결하지 않고도 Amplify Hosting을 통해 웹 앱을 배포할 수 있습니다. 다음 네 가지 배포 옵션 중 하나를 사용할 수 있습니다.

  1. Amplify 콘솔에서 애플리케이션 폴더를 끌어서 놓습니다.

  2. 사이트의 빌드 아티팩트가 포함된 .zip 파일을 Amplify 콘솔에 끌어서 놓습니다.

  3. 사이트의 빌드 아티팩트가 포함된 .zip 파일을 Amazon S3 버킷에 업로드한 뒤, 해당 버킷을 Amplify 콘솔의 앱에 연결합니다.

  4. 사이트의 빌드 아티팩트가 포함된 .zip 파일이 위치한 퍼블릭 URL을 Amplify 콘솔에 입력합니다.

현재 Amplify 콘솔에서 애플리케이션 폴더를 끌어서 놓아 수동 배포를 수행할 때 문제가 발생하는 사례가 확인되고 있습니다. 이러한 배포 실패는 다음과 같은 이유로 발생할 수 있습니다.

  • 일시적 네트워크 문제 발생

  • 업로드 중 로컬 파일 변경

  • 브라우저 세션에서 많은 정적 자산을 한 번에 업로드하려는 경우

끌어서 놓기 업로드의 신뢰성을 개선하는 동안, 애플리케이션 폴더를 직접 끌어서 놓는 방식 대신 .zip 파일을 사용하는 것이 좋습니다.

특히, .zip 파일을 Amazon S3 버킷에 업로드하는 방식을 강력히 권장합니다. 이렇게 하면 Amplify 콘솔을 통해 파일이 업로드되지 않아 수동 배포의 신뢰성이 향상됩니다. Amplify와 Amazon S3의 통합으로 이 과정을 쉽게 처리할 수 있습니다. 자세한 내용은 Amazon S3 버킷에서 Amplify에 정적 웹 사이트 배포 단원을 참조하십시오.

내 애플리케이션의 Node.js 버전을 업데이트해야 함

Amplify는 Node.js 14, 16, 18 버전을 사용하는 앱에 대한 지원을 2025년 9월 15일에 종료합니다. 해당 날짜 이후의 동작은 애플리케이션 유형에 따라 달라집니다.

  • SSR 애플리케이션: 지원 종료된 Node.js 버전을 계속 사용하면 빌드 오류가 발생합니다. Node.js 20 이상으로 업그레이드하지 않으면 업데이트 배포가 불가능합니다.

  • 비SSR 애플리케이션: buildspec 또는 라이브 패키지 업데이트를 통해 수동으로 설치하는 경우, 지원 종료된 Node.js 버전을 계속 사용할 수 있습니다.

이미 배포된 애플리케이션은 사용 중인 Node.js 버전에 관계없이 계속 실행됩니다.

Amazon Linux 2023 빌드 이미지를 사용하는 경우, 기본적으로 Node.js 20을 지원합니다. 2025년 9월 15일부터 AL2023 이미지는 자동으로 Node.js 22를 지원하며, 기본 Node.js 버전도 18에서 22로 변경됩니다.

Amazon Linux 2(AL2)는 Node.js 20 이상 버전을 자동으로 지원하지 않습니다. 현재 AL2를 사용 중이라면 AL2023으로 전환하는 것이 좋습니다. 빌드 이미지는 Amplify 콘솔에서 변경할 수 있습니다. 지정한 Node.js 버전을 지원하는 사용자 지정 빌드 이미지를 사용할 수도 있습니다.

업그레이드 전에, 새 브랜치에서 애플리케이션을 테스트하여 애플리케이션이 정상적으로 동작하는지 확인하는 것이 좋습니다.

업그레이드 옵션

Amplify 콘솔

Amplify 콘솔의 라이브 패키지 업데이트 기능을 사용해 사용할 Node.js 버전을 지정할 수 있습니다. 지침은 빌드 이미지에서 특정 패키지 및 종속성 버전 사용 섹션을 참조하세요.

사용자 지정 빌드 이미지

사용자 지정 빌드 이미지를 사용 중이고 이미지에 NVM이 설치되어 있다면, Dockerfile에 nvm install 20을 추가할 수 있습니다. 사용자 지정 빌드 이미지의 요구 사항 및 구성 방법에 대한 자세한 내용은 빌드 이미지 사용자 지정 섹션을 참조하세요.

빌드 설정

애플리케이션의 amplify.yml 빌드 설정에서 preBuild 명령 섹션에 nvm use 명령을 추가하여 사용할 Node.js 버전을 지정할 수 있습니다. 애플리케이션의 빌드 설정 업데이트 방법은 Amplify 애플리케이션의 빌드 설정 구성 섹션을 참조하세요.

아래 예제에서는 빌드 설정을 사용자 지정하여 기본 Node.js 버전을 Node.js 18로 설정하고, 테스트 브랜치인 node-20에서 Node.js 20으로 업그레이드하는 방법을 보여줍니다.

frontend:
  phases:
    preBuild:
      commands:
        - nvm use 18
        - if [ "${AWS_BRANCH}" = "node-20" ]; then nvm use 20; fi
주의

preBuild 명령은 라이브 패키지 업데이트 이후에 실행된다는 점에 유의하세요. nvm use 명령으로 지정한 Node.js 버전은 라이브 패키지 업데이트에서 설정한 Node.js 버전을 덮어씁니다.