폰트 CDN 변경으로 콘솔 404 에러 제거
목차
Pretendard 한글 폰트 라이브러리의 CDN 경로를 GitHub에서 npm 기반으로 변경해서 콘솔의 파일 누락 에러를 제거했다. 작아 보이는 작업이지만 의존성 관리와 배포 구조 사이의 미묘한 충돌을 다루는 경험이었다.
문제: 브라우저 콘솔에서 나오는 폰트 로딩 실패
프로덕션 환경에서 콘솔을 열면 Pretendard 폰트 파일에 대한 404 에러가 떨어졌다. 사용자가 겪는 실질적인 장애는 아니었지만(폰트가 로드되지 않는 것도 아니고), 배포 후 콘솔에 남는 에러는 팀 차원에서 정리해야 할 기술 채무였다. 특히 모니터링 시스템에서 클라이언트 에러로 수집되고 있어서 신호 대 잡음비를 떨어뜨리고 있었다.
원인: 버전과 CDN의 불일치
v1.3.9의 Pretendard를 GitHub CDN 경로로 불러오고 있었는데, 해당 버전의 GitHub 릴리스에는 woff2 포맷 파일이 포함되지 않았다. 반면 npm 저장소의 같은 버전에는 모든 포맷이 갖춰져 있었다.
흔한 상황이다. 오픈소스 라이브러리가 여러 배포 채널(GitHub, npm, jsDelivr 등)을 지원할 때 버전마다 포함 내용이 조금씩 달라질 수 있다. GitHub는 소스와 바이너리를 섞어서 보관하기 쉽고, npm은 배포 과정에서 빌드된 결과물만 패키징한다.
| 채널 | v1.3.9 woff2 포함 | 문제점 |
|---|---|---|
| GitHub | ❌ | 404 에러 발생 |
| npm | ✅ | 완전한 파일셋 |
| jsDelivr | ✅ (npm 미러) | 대안은 있었음 |
해결: npm 기반 CDN으로 통합
public/styles.css 의 @font-face 선언을 GitHub 직접 링크에서 npm 기반 CDN(예: unpkg, jsDelivr)으로 변경했다.
/* before: GitHub에서 직접 */
@font-face {
font-family: 'Pretendard';
src: url('https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/static/pretendard.woff2') format('woff2');
}
/* after: npm 저장소 경로 */
@font-face {
font-family: 'Pretendard';
src: url('https://unpkg.com/[email protected]/dist/web/static/pretendard.woff2') format('woff2');
}
npm 기반 CDN은 패키지 매니저의 공식 빌드 결과물을 제공하므로 버전별 일관성이 훨씬 높다. GitHub의 릴리스 탭이 완전하지 않을 때도 있지만, npm은 배포 프로세스 자체가 구조화되어 있기 때문이다.
팀과 비용 관점에서 본 영향
즉시적 효과:
- 콘솔 에러 제거 → 모니터링 노이즈 감소
- 클라이언트 에러 로그의 신뢰성 향상 (실제 버그에만 집중)
운영상 이점:
- npm 경로는 버전 업그레이드 시에도 일관성 유지 → 다음 버전 도입 때 같은 문제 반복 가능성 낮음
- CDN 자체가 변해도 npm 저장소 구조는 표준 → 마이그레이션 필요 없음
학습한 점:
오픈소스 라이브러리를 여러 채널에서 제공할 때, 각 채널의 버전이 정말 동일한지 확인하는 것이 중요하다. GitHub에서 "v1.3.9 릴리스가 있다"는 것과 "npm에 1.3.9가 배포됐다"는 것은 다를 수 있다. 특히 폰트, 빌드 결과물, 정적 자산을 다루는 프로젝트라면 더욱.
비슷한 상황에서의 대처법
앞으로 이런 의존성 관련 이슈를 만날 때:
- 첫 번째: 에러 메시지의 URL을 직접 방문해본다 (실제로 파일이 있는지 확인)
- 두 번째: 라이브러리 공식 문서에서 "권장 CDN"을 확인한다 (보통 npm 기반이 first-class)
- 세 번째: 버전 변경 시에는 두 채널의 파일 목록을 비교한다 (npm + jsDelivr API나 웹 UI 활용)
- 네 번째: 모니터링에 폰트 로딩 실패를 명시적으로 추적하도록 고민한다 (흐릿한 404 vs 명확한 Resource Timing API)
작은 CSS 변경이지만, 이렇게 한 줄 한 줄이 모니터링 품질과 팀의 신뢰할 수 있는 시그널을 만든다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.