Firebase CORS 오류 해결: Storage 이미지 업로드가 막힐 때 확인할 설정

학습 목표와 사전 지식

목표: Storage 업로드 실패에서 CORS·인증·버킷 설정을 분리하고 필요한 CORS만 수정합니다.
사전 지식: Origin 개념, Network 탭, Cloud Storage 버킷 관리 권한

CORS는 브라우저가 다른 출처 응답을 읽을 수 있는지 정하는 정책입니다. Storage Rules가 허용할 사용자와 객체를 정하는 것과 다릅니다. 콘솔의 CORS 문구 하나로 Rules나 버킷을 전부 공개하지 마세요.

요청 종류부터 고정하기

실패한 요청의 호스트, HTTP 메서드, Origin, OPTIONS 응답, 최종 상태 코드와 SDK error.code를 기록합니다. Firebase Web SDK 업로드인지, getBlob/getBytes 직접 다운로드인지, 직접 만든 fetch 업로드인지 먼저 구분합니다. 잘못된 bucket이나 API 응답이 CORS 문구 뒤에 가려질 수 있으므로 SDK 오류와 Console의 객체 존재 여부도 함께 봅니다.

관찰	다음 확인
storage/unauthorized	로그인 상태·경로·Storage Rules
storage/object-not-found	실제 객체 이름·bucket
OPTIONS 또는 응답에 CORS 헤더 없음	실제 요청 Origin과 버킷 CORS
storage/quota-exceeded	프로젝트 플랜·사용량·버킷 접근 조건

cors.json: 필요한 출처와 메서드만

아래는 직접 파일을 읽는 GET/HEAD 예시입니다. 업로드 요청에서 실제로 PUT 또는 POST가 필요한 것을 확인한 경우 그 메서드를 추가합니다. OPTIONS 자체를 CORS method 목록에 추가하지 않습니다. origin에는 경로를 제외한 프로토콜·호스트·포트가 들어갑니다. http://localhost:3000과 http://localhost:5173은 다릅니다.

cors.json · 전체 설정 파일; 예시 출처를 실제 소유 출처로 교체

[
  {
    "origin": [
      "http://localhost:3000",
      "https://example.com"
    ],
    "method": [
      "GET",
      "HEAD"
    ],
    "responseHeader": [
      "Content-Type"
    ],
    "maxAgeSeconds": 3600
  }
]

터미널 · 버킷 소유 프로젝트에서 실행할 명령; 여기서는 미실행

gcloud storage buckets describe gs://YOUR_BUCKET --format="default(cors_config)"
gcloud storage buckets update gs://YOUR_BUCKET --cors-file=cors.json
gcloud storage buckets describe gs://YOUR_BUCKET --format="default(cors_config)"

수정 전·후 비교

먼저 기존 CORS를 별도 파일로 보관합니다. 위 설정은 CORS 목록을 교체하므로 기존 운영 Origin을 누락시키지 마세요. 변경 후 같은 요청을 DevTools의 캐시 비활성화 상태에서 다시 보냅니다. preflight 캐시가 남을 수 있어 새로운 시크릿 세션에서도 확인합니다. 응답을 읽을 수 있고 원래 요청이 성공해야 해결이며, CORS 문구만 사라지고 403이 남으면 권한 문제는 아직 남아 있습니다.

브라우저 밖의 검사에는 한계가 있습니다

curl이나 새 탭 직접 접근은 CORS 정책을 동일하게 적용하지 않습니다. 성공해도 fetch의 성공을 증명하지 못합니다. 다운로드 token URL과 인증 SDK 요청은 인증 수단도 다르므로 같은 요청으로 취급하지 않습니다. 계정 권한과 파일 크기·유형 검사는 Storage Rules에 유지하세요.

직접 확인할 결과

기존 CORS 백업과 변경 후 목록 대조
동일 Origin·메서드 브라우저 재시도
403·404와 CORS 해결 여부 별도 기록

사용 전 플랜 확인

2026-09-13 공식 문서 기준 Cloud Storage for Firebase는 기본 버킷 접근을 포함해 Blaze 종량제 플랜이 필요합니다. 무료 사용량과 결제 플랜은 다른 개념입니다. 개발 프로젝트의 결제 연결·예산 알림·실제 사용량을 확인하세요.

검증 범위와 기준일

공식 문서 확인일: 2026-09-13. 웹 SDK 예제는 모듈형 API 기준입니다. 이 글의 코드·구조 정적 검토와 실제 클라우드 인증·저장·배포 검증을 구분합니다. 본인 개발 Firebase 프로젝트의 실제 인증·권한·배포 요청은 이 편집 환경에서 실행하지 않았습니다.

이어서 학습하기

• Firebase Storage 이미지 오류 해결: 403·404·token·Rules 확인법
• Firebase 실무 오류 해결 모음: Storage, Firestore, Auth 체크리스트

공식 문서

• https://cloud.google.com/storage/docs/using-cors
• https://firebase.google.com/docs/storage/web/download-files
• https://firebase.google.com/docs/storage/web/handle-errors