문제 해결

자주 발생하는 오류

오류	원인	해결 방법
`BucketAlreadyExists`	버킷 이름이 이미 사용 중	이름 뒤에 랜덤 문자열 추가
`AccessDenied`	AWS 권한 부족	IAM 권한 확인
`Build directory not found`	빌드 파일이 없음	`npm run build` 먼저 실행
`Credentials not found`	AWS 인증 미설정	`aws configure` 실행
`CertificateNotFound`	인증서가 다른 리전에 있음	`us-east-1`에서 인증서 발급

AWS 인증 설정

bash

# 인증 정보 설정
aws configure

# 또는 환경 변수로 설정
export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

S3 버킷 이름

버킷 이름은 전 세계에서 유일해야 합니다:

typescript

s3: {
  bucketName: 'my-site-abc123', // 뒤에 랜덤 문자열 추가
}

필요한 AWS 권한

json

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "s3:*",
      "cloudfront:*",
      "acm:*",
      "route53:*"
    ],
    "Resource": "*"
  }]
}

CloudFront 관련

처음 배포할 때 15~30분 정도 걸립니다
상태 확인: npx scf-deploy status
SSL 인증서는 반드시 us-east-1 리전에 있어야 합니다

TTL 설정이 작동하지 않음 (v2.0.0+)

원인: v2.0.0에서 TTL 설정 (defaultTTL, maxTTL, minTTL)이 제거되었습니다.

해결 방법:

scf.config.ts에서 TTL 필드를 제거하세요
TTL은 이제 AWS Managed Cache Policy (CachingOptimized)에서 자동으로 관리됩니다
커스텀 TTL 값이 필요한 경우 AWS Console에서 직접 설정하세요

typescript

// v2.0.0+에서 제거해야 할 옵션
cloudfront: {
  defaultTTL: 3600,  // ❌ 제거
  maxTTL: 86400,     // ❌ 제거
  minTTL: 0,         // ❌ 제거
}

자세한 내용은 v1.x에서 마이그레이션을 참조하세요.

설정 파일을 못 찾는 경우

bash

# 설정 파일 경로를 직접 지정
npx scf-deploy deploy --config ./path/to/scf.config.ts

도움이 더 필요하신가요?

GitHub Issues에서 검색
새 이슈 작성 시 포함할 내용:
- 오류 메시지 전체
- 재현 방법
- Node.js 버전, OS 정보