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

SSR 지원되는 기능

이 섹션에서는 Amplify의 SSR 기능 지원에 대한 정보를 제공합니다.

Amplify는 앱을 빌드하는 데 사용된 Node.js 버전과 일치하도록 Node.js 버전 지원을 제공합니다.

Amplify는 모든 SSR 앱을 지원하는 기본 제공 이미지 최적화 기능을 제공합니다. 기본 이미지 최적화 기능을 사용하지 않으려면 사용자 지정 이미지 최적화 로더를 구현할 수 있습니다.

Next.js 앱에 대한 Node.js 버전 지원

Amplify가 Next.js 컴퓨팅 앱을 빌드하고 배포하면 Node.js 의 메이저 버전과 일치하는 런타임 버전 Node.js 앱을 빌드하는 데 사용된 입니다.

를 지정할 수 있습니다.Node.js Amplify 콘솔의 라이브 패키지 재정의 기능에 사용할 버전입니다. 라이브 패키지 업데이트 구성에 대한 자세한 내용은 빌드 이미지에서 특정 패키지 및 종속성 버전 사용 섹션을 참조하세요. 또한 를 지정할 수 있습니다.Node.js 다음과 같은 다른 메커니즘을 사용하는 버전 nvm 명령. 버전을 지정하지 않으면 Amplify에서는 Amplify 빌드 컨테이너에서 사용되는 현재 버전을 기본적으로 사용합니다.

SSR 앱의 이미지 최적화

Amplify Hosting은 모든 SSR 앱을 지원하는 기본 제공 이미지 최적화 기능을 제공합니다. Amplify의 이미지 최적화를 통해 가능한 한 가장 작은 파일 크기를 유지하면서 해당 이미지에 액세스하는 디바이스에 적합한 형식, 크기 및 해상도로 고품질 이미지를 전달할 수 있습니다.

현재 Next.js Image 구성 요소를 사용하여 온디맨드 방식으로 이미지를 최적화하거나 사용자 지정 이미지 로더를 구현할 수 있습니다. Next.js 13 이상을 사용한다면 Amplify의 이미지 최적화 기능을 사용하기 위해 별도의 조치를 취하지 않아도 됩니다. 사용자 지정 로더를 구현하는 경우 이어지는 사용자 지정 이미지 로더 사용을 참조하세요.

사용자 지정 이미지 로더 사용

사용자 지정 이미지 로더를 사용하면 Amplify에서는 애플리케이션의 next.config.js 파일에서 로더를 감지하며 기본으로 제공되는 이미지 최적화 기능을 활용하지 않습니다. Next.js에서 지원하는 사용자 지정 로더에 대한 자세한 내용은 Next.js 이미지 설명서를 참조하세요.

SSR 앱용 Amazon CloudWatch Logs

Amplify는 SSR 런타임에 대한 정보를 의 Amazon CloudWatch Logs로 전송합니다 AWS 계정. SSR 앱을 배포할 때 앱을 사용하려면 Amplify가 사용자를 대신하여 다른 IAM 서비스를 호출할 때 수임하는 서비스 역할이 필요합니다. Amplify Hosting 컴퓨팅이 자동으로 서비스 역할을 생성하도록 허용하거나 사용자가 생성한 역할을 지정할 수 있습니다.

Amplify가 사용자를 대신하여 IAM 역할을 생성하도록 허용하도록 선택하면 해당 역할에는 이미 CloudWatch 로그를 생성할 권한이 있습니다. 자체 IAM 역할을 생성하는 경우 Amplify가 Amazon CloudWatch Logs에 액세스할 수 있도록 정책에 다음 권한을 추가해야 합니다.

logs:CreateLogStream
logs:CreateLogGroup
logs:DescribeLogGroups
logs:PutLogEvents

서비스 역할에 대한 자세한 내용은 Amplify 앱에 서비스 역할 추가을 참조하십시오.

Amplify Next.js 11 SSR 지원

2022년 11월 17일에 Amplify 호스팅 컴퓨팅이 출시되기 전에 Amplify에 Next.js 앱을 배포한 경우 앱은 Amplify의 이전 SSR 공급자인 Classic(Next.js 11만 해당)을 사용하고 있습니다. 이 섹션의 설명서는 Classic(Next.js 11만 해당) SSR 공급자를 사용하여 배포된 앱에만 적용됩니다.

다음 목록은 Amplify Classic(Next.js 11만 해당) SSR 공급자가 지원하는 특정 기능을 설명합니다.

Next.js 11 SSR 앱 요금

Next.js 11 SSR 앱을 배포할 때 Amplify는 AWS 계정에 다음을 포함한 추가 백엔드 리소스를 생성합니다.

AWS Identity and Access Management Next.js 11 SSR 앱에 대한 권한

Amplify는 SSR 앱을 배포하려면 AWS Identity and Access Management (IAM) 권한이 필요합니다. 필요한 최소 권한이 없으면 SSR 앱을 배포하려고 할 때 오류가 발생합니다. Amplify에 필요한 권한을 제공하려면 서비스 역할을 지정해야 합니다.

사용자를 대신하여 다른 IAM 서비스를 호출할 때 Amplify가 수임하는 서비스 역할을 생성하려면 섹션을 참조하세요Amplify 앱에 서비스 역할 추가. 이 지침은 AdministratorAccess-Amplify 관리형 정책을 연결하는 역할을 생성하는 방법을 설명합니다.

AdministratorAccess-Amplify 관리형 정책은 IAM 작업을 포함한 여러 AWS 서비스에 대한 액세스를 제공합니다. 및 는 AdministratorAccess 정책만큼 강력해야 합니다. 이 정책은 SSR 앱을 배포하는 데 필요한 것보다 더 많은 권한을 제공합니다.

최소 권한을 부여하는 모범 사례를 따르고 서비스 역할에 부여되는 권한을 줄이는 것이 좋습니다. 관리자에게 서비스 역할에 대한 액세스 권한을 부여하는 대신 SSR 앱을 배포하는 데 필요한 권한만 부여하는 자체 고객 관리형 IAM 정책을 생성할 수 있습니다. 고객 관리형 IAM 정책 생성에 대한 지침은 IAM 사용 설명서의 정책 생성을 참조하세요.

자체 정책을 생성하는 경우 SSR 다음 앱 배포에 필요한 최소 권한 목록을 참조하세요.

acm:DescribeCertificate
acm:ListCertificates
acm:RequestCertificate
cloudfront:CreateCloudFrontOriginAccessIdentity
cloudfront:CreateDistribution
cloudfront:CreateInvalidation
cloudfront:GetDistribution
cloudfront:GetDistributionConfig
cloudfront:ListCloudFrontOriginAccessIdentities
cloudfront:ListDistributions
cloudfront:ListDistributionsByLambdaFunction
cloudfront:ListDistributionsByWebACLId
cloudfront:ListFieldLevelEncryptionConfigs
cloudfront:ListFieldLevelEncryptionProfiles
cloudfront:ListInvalidations
cloudfront:ListPublicKeys
cloudfront:ListStreamingDistributions
cloudfront:UpdateDistribution
cloudfront:TagResource
cloudfront:UntagResource
cloudfront:ListTagsForResource
cloudfront:DeleteDistribution
iam:AttachRolePolicy
iam:CreateRole
iam:CreateServiceLinkedRole
iam:GetRole
iam:PutRolePolicy
iam:PassRole
iam:UpdateAssumeRolePolicy
iam:DeleteRolePolicy
lambda:CreateFunction
lambda:EnableReplication
lambda:DeleteFunction
lambda:GetFunction
lambda:GetFunctionConfiguration
lambda:PublishVersion
lambda:UpdateFunctionCode
lambda:UpdateFunctionConfiguration
lambda:ListTags
lambda:TagResource
lambda:UntagResource
lambda:ListEventSourceMappings
lambda:CreateEventSourceMapping
route53:ChangeResourceRecordSets
route53:ListHostedZonesByName
route53:ListResourceRecordSets
s3:CreateBucket
s3:GetAccelerateConfiguration
s3:GetObject
s3:ListBucket
s3:PutAccelerateConfiguration
s3:PutBucketPolicy
s3:PutObject
s3:PutBucketTagging
s3:GetBucketTagging
sqs:CreateQueue
sqs:DeleteQueue
sqs:GetQueueAttributes
sqs:SetQueueAttributes
amplify:GetApp
amplify:GetBranch
amplify:UpdateApp
amplify:UpdateBranch

Next.js 11 SSR 배포 문제 해결

Amplify와 함께 Classic(Next.js 11만 해당) SSR 앱을 배포할 때 예기치 않은 문제가 발생하는 경우 다음 문제 해결 주제를 검토하세요.

애플리케이션의 출력 디렉터리가 재정의됨

Amplify로 배포된 Next.js 앱의 출력 디렉토리는 .next으로 설정되어야 합니다. 앱의 출력 디렉토리가 재정의되는 경우 next.config.js 파일을 확인합니다. 빌드 출력 디렉터리의 기본값을 .next으로 설정하려면 파일에서 다음 줄을 삭제합니다.

distDir: 'build'

빌드 설정에서 출력 디렉터리가 .next으로 설정되어 있는지 확인합니다. 앱의 빌드 설정을 보는 방법에 대한 자세한 내용은 앱의 빌드 설정 구성 섹션을 참조하십시오.

다음은 baseDirectory가 .next으로 설정된 앱의 빌드 설정 예시입니다.

version: 1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

SSR 사이트를 배포한 후 404 오류가 발생합니다.

사이트를 배포한 후 404 오류가 발생하는 경우, 출력 디렉터리가 재정의되어 문제가 발생한 것일 수 있습니다. next.config.js 파일을 확인하고 앱 빌드 사양의 빌드 출력 디렉터리가 올바른지 확인하려면 이전 애플리케이션의 출력 디렉터리가 재정의됨 주제의 단계를 따릅니다.

애플리케이션에 배포에 대한 CloudFront SSR 재작성 규칙이 누락되었습니다.

SSR 앱을 배포할 때 Amplify는 배포에 대한 CloudFront SSR 재작성 규칙을 생성합니다. 웹 브라우저에서 앱에 액세스할 수 없는 경우 Amplify 콘솔에서 앱에 CloudFront 대한 재작성 규칙이 있는지 확인합니다. 규칙이 없는 경우 수동으로 추가하거나 앱을 재배포할 수 있습니다.

Amplify 콘솔에서 앱의 다시 쓰기 및 리디렉션 규칙을 보거나 편집하려면, 탐색 창에서 앱 설정을 선택한 다음 다시 쓰기 및 리디렉션을 선택합니다. 다음 스크린샷은 Amplify가 SSR 앱을 배포할 때 생성하는 재작성 규칙의 예를 보여줍니다. 이 예제에서는 CloudFront 재작성 규칙이 존재합니다.

애플리케이션이 너무 커서 배포할 수 없음

Amplify는 SSR 배포 크기를 50MB로 제한합니다. Amplify에 Next.js SSR 앱을 배포하려고 하는데 RequestEntityTooLargeException 오류가 발생하면 앱이 너무 커서 배포할 수 없습니다. next.config.js 파일에 캐시 정리 코드를 추가하여 이 문제를 해결할 수 있습니다.

다음은 캐시 정리를 수행하는 next.config.js 파일 내 코드의 예입니다.

module.exports = {
    webpack: (config, { buildId, dev, isServer, defaultLoaders, webpack }) => {
        config.optimization.splitChunks.cacheGroups = { }
        config.optimization.minimize = true;
        return config
      },
}

메모리 부족 오류로 인해 빌드가 실패함

Next.js를 통해 빌드 아티팩트를 캐시하여 후속 빌드의 성능을 개선할 수 있습니다. 또한 Amplify의 AWS CodeBuild 컨테이너는 후속 빌드 성능을 개선하기 위해 사용자를 대신하여 이 캐시를 압축하고 Amazon S3에 업로드합니다. 이로 인해 메모리 부족 오류가 발생하면 빌드가 실패할 수 있습니다.

빌드 단계에서 앱이 메모리 제한을 초과하지 않도록 하려면 다음 작업을 수행합니다. 먼저 빌드 설정의 cache.paths 섹션에서 .next/cache/**/*를 삭제합니다. 그런 다음, 빌드 설정 파일에서 NODE_OPTIONS 환경 변수를 제거합니다. 대신 Amplify 콘솔에서 NODE_OPTIONS 환경 변수를 설정하여 노드 최대 메모리 제한을 정의합니다. Amplify 콘솔을 사용하여 환경 변수를 설정하는 방법에 대한 자세한 내용은 환경 변수 설정을 참조하십시오.

이러한 변경을 수행한 후 빌드를 다시 시도합니다. 빌드가 성공하면 빌드 설정 파일의 cache.paths 섹션에 .next/cache/**/*를 다시 추가합니다.

빌드 성능을 개선하기 위한 Next.js 캐시 구성AWS CodeBuild에 대한 자세한 내용은 Next.js 웹 사이트의 섹션을 참조하세요.

내 애플리케이션에는 SSR 및 SSG브랜치가 모두 있습니다.

SSR 및 SSG브랜치가 모두 있는 앱은 배포할 수 없습니다. SSR 및 SSG브랜치를 모두 배포해야 하는 경우 브랜치만 사용하는 앱 하나와 브SSR랜치만 사용하는 다른 앱을 배포해야 합니다SSG.

애플리케이션이 예약된 경로의 폴더에 정적 파일을 저장 중임

Next.js는 프로젝트의 루트 디렉터리에 이름이 public으로 지정되어 저장된 폴더의 정적 파일을 제공할 수 있습니다. Amplify를 사용하여 Next.js 앱을 배포하고 호스팅하는 경우 프로젝트에 public/static 경로가 있는 폴더를 포함할 수 없습니다. Amplify는 앱을 배포할 때 사용할 public/static 경로를 예약합니다. 앱에 이 경로가 포함된 경우, Amplify로 배포하기 전에 static 폴더 이름을 변경해야 합니다.

애플리케이션이 한도에 CloudFront 도달했습니다.

CloudFront 서비스 할당량은 Lambda@Edge 함수가 연결된 25개의 배포로 AWS 계정을 제한합니다. 이 할당량을 초과하는 경우 계정에서 미사용 CloudFront 배포를 삭제하거나 할당량 증가를 요청할 수 있습니다. 자세한 내용은 Service Quotas 사용 설명서의 할당량 증가 요청을 참조하십시오.

환경 변수가 Lambda 함수로 전달되지 않음

SSR Amplify 콘솔에서 앱에 지정하는 환경 변수는 앱의 AWS Lambda 함수로 전달되지 않습니다. Lambda 함수에서 참조할 수 있는 환경 변수를 추가하는 방법에 대한 자세한 지침은 환경 변수가 서버 측 런타임에 액세스할 수 있도록 만들기 섹션을 참조하십시오.

Lambda@Edge 함수가 미국 동부(버지니아 북부) 리전에서 생성됨

Next.js 앱을 배포할 때 Amplify는 Lambda@Edge 함수를 생성하여 가 CloudFront 제공하는 콘텐츠를 사용자 지정합니다. Lambda@Edge 함수는 앱이 배포된 리전이 아닌 미국 동부(버지니아 북부) 리전에서 생성됩니다. 이는 Lambda@Edge의 제한 사항입니다. Lambda@Edge 함수에 대한 자세한 내용은 Amazon 개발자 안내서의 엣지 함수 제한을 참조하세요. CloudFront

Next.js 애플리케이션이 지원되지 않는 기능을 사용함

Amplify로 배포된 앱은 버전 11까지의 Next.js 메이저 버전을 지원합니다. Amplify에서 지원되거나 지원되지 않는 Next.js 기능의 상세 목록은 supported features 섹션을 참조하십시오.

새 Next.js 앱 배포 시 Amplify는 지원되는 가장 최신 버전의 Next.js를 기본적으로 사용합니다. 이전 버전의 Next.js로 Amplify에 배포한 기존 Next.js 앱이 있는 경우 앱을 Amplify 호스팅 컴퓨팅 SSR 공급자로 마이그레이션할 수 있습니다. 지침은 Next.js 11 SSR 앱을 Amplify Hosting 컴퓨팅으로 마이그레이션 단원을 참조하십시오.

Next.js 애플리케이션의 이미지가 로드되지 않음

next/image 구성 요소를 사용하여 Next.js 앱에 이미지를 추가할 때, 이미지 크기는 1MB를 초과할 수 없습니다. Amplify에 앱을 배포할 때 이미지가 1MB보다 큰 경우 503 오류를 반환합니다. 이는 헤더 및 본문을 포함하여 Lambda 함수가 생성하는 응답의 크기를 1MB로 제한하는 Lambda@Edge 제한 때문입니다.

1MB 제한은 PDF 및 문서 파일과 같은 앱의 다른 아티팩트에 적용됩니다.

지원되지 않는 리전

Amplify는 Amplify를 사용할 수 있는 모든 AWS 리전에서 Classic(Next.js 11만 해당) SSR 앱 배포를 지원하지 않습니다. 유럽(밀라노) eu-south-1, 중동(바레인) me-south-1, 아시아 태평양(홍콩) ap-east-1 리전에서는 Classic(Next.js 11만 해당)SSR이 지원되지 않습니다.