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

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

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

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

SSR앱용 Amazon CloudWatch 로그

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 Next.js 11 지원 SSR

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

참고

Next.js 11 앱을 Amplify 호스팅 컴퓨팅 관리 SSR 공급자로 마이그레이션하는 것이 좋습니다. 자세한 내용은 Next.js 11 SSR 앱을 Amplify 호스팅 컴퓨트로 마이그레이션하기 단원을 참조하십시오.

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

지원되는 기능

• 서버측 렌더링된 페이지 () SSR

• 정적 페이지

• API경로

• 동적 라우팅

• 모든 라우팅 포착

• SSG(정적 생성)

• 점진적 정적 재생 () ISR

• 다국어(i18n) 하위 경로 라우팅

• 환경 변수

지원되지 않는 기능

• 이미지 최적화

• 온디맨드 점진적 정적 재생 () ISR

• 다국어(i18n) 도메인 라우팅

• 다국어(i18n) 자동 로케일 감지

• 미들웨어

• 엣지 미들웨어

• 에지 루트 API

Next.js 11 SSR 앱의 요금

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

• 앱의 정적 자산에 대한 리소스를 저장하는 Amazon Simple Storage Service(S3) 버킷. Amazon S3 요금에 대한 자세한 내용은 Amazon S3 요금을 참조하십시오.

• 앱을 제공하기 위한 Amazon CloudFront 배포판입니다. CloudFront 요금에 대한 자세한 내용은 Amazon CloudFront 요금을 참조하십시오.

• 제공하는 콘텐츠를 사용자 지정하는 네 개의 Lambda @Edge 함수. CloudFront

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

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

사용자 대신 다른 IAM 서비스를 호출할 때 Amplify가 맡는 서비스 역할을 생성하려면 을 참조하십시오. 서비스 역할 추가 이 지침은 AdministratorAccess-Amplify 관리형 정책을 연결하는 역할을 생성하는 방법을 설명합니다.

AdministratorAccess-Amplify관리형 정책은 여러 항목에 대한 액세스를 제공합니다. AWS IAM작업을 포함한 서비스는 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를 사용하여 클래식 (Next.js 11만 해당) SSR 앱을 배포할 때 예상치 못한 문제가 발생하는 경우 다음 문제 해결 항목을 검토하십시오.

주제

• 출력 디렉터리가 재정의됨
• 사이트를 배포한 후 404 오류가 발생합니다. SSR
• 앱에 배포에 대한 재작성 규칙이 누락되었습니다. CloudFront SSR
• 앱이 너무 커서 배포할 수 없음
• 메모리 부족 오류로 인해 빌드가 실패함
• 앱에는 두 SSG 가지 SSR 및 브랜치가 모두 있습니다.
• 앱은 예약된 경로가 있는 폴더에 정적 파일을 저장합니다.
• 앱이 CloudFront 한도에 도달했습니다.
• 환경 변수가 Lambda 함수로 전달되지 않음
• Lambda@Edge 함수가 미국 동부(버지니아 북부) 리전에서 생성됨
• Next.js 앱이 지원되지 않는 기능을 사용함
• Next.js 앱의 이미지가 로드되지 않음
• 지원되지 않는 리전

출력 디렉터리가 재정의됨

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/**/*

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

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

앱에 배포에 대한 재작성 규칙이 누락되었습니다. CloudFront SSR

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

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

앱이 너무 커서 배포할 수 없음

Amplify는 SSR 배포 크기를 50MB로 제한합니다. Next.js SSR 앱을 Amplify에 배포하려고 할 때 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 캐시 구성에 대한 자세한 내용은 Next.js 웹 AWS CodeBuild사이트를 참조하십시오.

앱에는 두 SSG 가지 SSR 및 브랜치가 모두 있습니다.

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

앱은 예약된 경로가 있는 폴더에 정적 파일을 저장합니다.

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

앱이 CloudFront 한도에 도달했습니다.

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

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

Amplify 콘솔에서 앱에 지정한 환경 변수는 SSR 앱의 환경 변수로 전달되지 않습니다. 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 호스팅 컴퓨트로 마이그레이션하기 단원을 참조하십시오.

Next.js 앱의 이미지가 로드되지 않음

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

앱 내 다른 아티팩트 (예: 문서 파일) 에는 1MB 제한이 적용됩니다. PDF

지원되지 않는 리전

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