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

브라우저 콘솔에 CORS 정책 오류가 보이면 Firebase 문제인지, CORS 설정 문제인지, 요청 방식 문제인지 구분하기 어렵습니다.

• CORS 오류와 권한 오류를 먼저 구분합니다
• 브라우저 요청의 출처를 확인합니다
• CORS 설정은 버킷에 적용해야 합니다
• Storage Rules는 인증과 파일 경로 기준을 담당합니다
• 로컬과 배포 도메인을 따로 점검합니다
• 발행 전 마지막 점검 기준
• 실제 작업에서는 재현 조건을 먼저 고정합니다
• 같은 오류가 반복되지 않게 기록할 것

CORS 오류와 권한 오류를 먼저 구분합니다

Firebase에서 이미지 업로드가 막힐 때 콘솔에 CORS라는 단어가 보이면 모두 같은 문제처럼 느껴집니다. 하지만 실제로는 브라우저가 요청을 차단한 CORS 문제일 수도 있고, Firebase Storage Rules에서 권한이 거부된 문제일 수도 있습니다. Firebase SDK의 storage/unauthorized 같은 오류나 Rules 거부 응답이면 Storage Rules를 보고, preflight 요청이나 Access-Control-Allow-Origin 메시지가 중심이면 CORS 설정과 요청 origin을 먼저 확인합니다.

브라우저 요청의 출처를 확인합니다

CORS는 브라우저가 서로 다른 출처로 요청을 보낼 때 적용되는 정책입니다. 로컬 개발 환경의 http://localhost:3000, 배포된 https 도메인, 관리자 페이지 도메인이 서로 다르게 취급됩니다. 버킷에 허용한 origin과 실제 요청 origin이 다르면 업로드나 다운로드가 막힐 수 있습니다. 먼저 Network 탭에서 요청 URL과 Origin 헤더를 확인합니다.

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

CORS 설정은 버킷에 적용해야 합니다

Firebase Storage의 CORS 설정은 코드 안에서 해결하는 것이 아니라 버킷 설정에 적용합니다. Google Cloud CLI나 관련 도구로 허용 origin, method, responseHeader, maxAgeSeconds를 지정합니다. 개발 중에는 localhost를 포함하고, 배포 후에는 실제 서비스 도메인을 포함해야 합니다. 다만 브라우저에서 직접 Cloud Storage 객체를 가져오는 방식은 사용하는 엔드포인트에 따라 CORS 동작이 달라질 수 있으므로, 실제 요청 URL도 함께 확인합니다. 모든 origin을 허용하는 설정은 빠르게 테스트할 수 있지만 운영 환경에서는 필요한 도메인만 허용하는 편이 안전합니다.

Storage Rules는 인증과 파일 경로 기준을 담당합니다

CORS 설정이 맞아도 Storage Rules에서 막히면 업로드는 실패합니다. 로그인 사용자만 업로드할 수 있는지, 경로 prefix나 파일명 패턴 기준으로 접근을 제한하는지, 파일 크기나 contentType 제한이 있는지 확인해야 합니다. 이미지 업로드라면 request.resource.contentType.matches('image/.*') 같은 조건을 사용할 수 있지만, 프론트엔드에서 보내는 파일 타입이 비어 있으면 예상과 다르게 막힐 수 있습니다.

공식 문서 기준으로 Firebase Storage Rules는 인증, 경로, 메타데이터 같은 접근 조건을 검사하고, Cloud Storage CORS는 버킷의 cross-origin 접근 정책으로 다뤄집니다. 자세한 기준은 Firebase Storage Security Rules 문서, Rules 조건 문서, Cloud Storage CORS 설정 문서를 함께 확인하면 좋습니다.

로컬과 배포 도메인을 따로 점검합니다

로컬에서는 업로드가 되는데 배포 후 막힌다면 CORS origin에 배포 도메인이 빠졌을 가능성이 있습니다. 반대로 배포는 되는데 로컬에서만 막히면 localhost 포트가 다르거나 http/https 차이가 원인일 수 있습니다. 최종 점검은 콘솔 에러 구분, Network origin 확인, CORS 설정, Storage Rules 조건, 실제 배포 도메인 순서로 진행합니다.

발행 전 마지막 점검 기준

이미지 업로드가 막히면 먼저 브라우저 CORS 문제인지, Storage Rules 권한 문제인지 나눠 봅니다. 두 문제는 콘솔에 비슷하게 보일 수 있지만 확인할 위치가 다릅니다.

• 콘솔과 Network 탭에서 Origin, 요청 URL, 응답 코드를 확인했는가?
• 버킷 CORS 설정에 로컬과 배포 도메인이 모두 들어 있는가?
• 업로드에 필요한 HTTP method와 response header가 허용되어 있는가?
• Storage Rules에서 로그인, 경로, 파일 크기, contentType 조건이 맞는가?
• 로컬 포트와 배포 도메인을 같은 origin으로 착각하지 않았는가?

실제 작업에서는 재현 조건을 먼저 고정합니다

CORS 문제는 실행 환경에 따라 다르게 보일 수 있습니다. 로컬에서는 http://localhost:3000, 배포 후에는 실제 HTTPS 도메인이 origin으로 들어가므로 같은 코드라도 버킷 설정이 다르면 결과가 달라집니다.

재현할 때는 요청한 파일 경로, 요청 method, Origin 헤더, 응답 코드, Storage Rules 조건을 함께 남깁니다. 이렇게 해야 CORS 설정 문제인지, 인증과 권한 문제인지 빠르게 분리할 수 있습니다.

같은 오류가 반복되지 않게 기록할 것

문제를 해결한 뒤에는 허용한 origin, method, responseHeader, 적용한 버킷 이름을 기록합니다. Storage Rules를 함께 수정했다면 어떤 경로와 조건을 바꿨는지도 남겨두는 것이 좋습니다.

특히 로컬 포트나 배포 도메인이 바뀌면 같은 오류가 다시 날 수 있습니다. 배포 전후로 CORS 설정과 Storage Rules를 같이 확인하는 기준을 남겨두면 다음 업로드 오류를 더 빨리 좁힐 수 있습니다.

관련 글을 대표 허브 기준으로 이어서 보기

이 글과 비슷한 문제는 Firebase 오류 해결 가이드에서 전체 흐름을 먼저 확인하면 검색 의도와 해결 순서를 더 분명하게 나눌 수 있습니다.

• 대표 허브: Firebase 오류 해결 가이드
• Firebase 실무 로드맵
• Firebase 초기화 구조
• Firebase Storage 이미지 오류 해결
• Firebase 보안 규칙 설계
• Firebase Auth Context 설계