Sentry 소스맵 배포 트러블슈팅: release/url prefix 불일치로 스택이 난독화될 때

Sentry 소스맵 배포 트러블슈팅: release/url prefix 불일치로 스택이 난독화될 때

Sentry 이벤트는 올라오는데 스택트레이스가 minified로 보이는 문제는 검색 수요가 매우 큽니다. 원인은 대부분 release 불일치, 소스맵 업로드 누락, url prefix(경로) 불일치입니다. 이 글은 CI에서 소스맵을 안정적으로 붙이는 체크리스트를 제공합니다.

소스맵은 빌드 결과와 Sentry 아티팩트가 정확히 매칭되어야 합니다.

옵션/핵심 요소(3~6개)

항목	의미	언제 쓰는지(실무 상황)
release	배포 식별자	코드에서 보내는 release와 업로드 release 일치
upload sourcemaps	소스맵 업로드	CI에서 빌드 후 업로드를 강제
url prefix	경로 매칭	브라우저가 로드하는 JS URL과 Sentry 경로 일치
hide sourcemaps	노출 제어	공개 노출을 피하고 Sentry에만 보관
환경 분리	staging/prod 분리	프로젝트/릴리스를 환경별로 분리

예시(개념)

// 핵심: 코드에서 보내는 release와 업로드 release를 동일하게 맞추기
release = gitSha 또는 buildNumber

문제 상황(정확히 1개)

상황: 스택이 at t (app-xxxxx.js:1:12345)처럼 난독화로만 보인다

원인: 소스맵 업로드가 누락되었거나, release/url prefix가 실제 배포된 JS와 매칭되지 않는다

해결: CI에서 소스맵 업로드를 배포 게이트로 만들고, release 값을 단일 기준(git SHA 등)으로 통일한다. 배포된 JS URL과 아티팩트 경로를 확인한다

예방 팁: 배포 파이프라인에 소스맵 업로드 성공을 강제하고, 실패 시 배포를 막는다

참고/출처

• Sentry: JavaScript Source Maps
• Sentry: Releases