웹폰트 CDN 마이그레이션으로 404 에러 제거

간단한 수정 같지만 꽤 흔한 문제를 건드렸다. Pretendard 폰트를 GitHub Pages 기반 CDN에서 npm CDN으로 변경했고, 그 결과 콘솔에 떠있던 404 에러를 깔끔하게 없앨 수 있었다.

왜 갑자기 CDN을 바꾸게 됐나

사실 처음엔 간단한 리포트였다. 개발자 도구의 콘솔을 열면 폰트 파일 로딩 실패 404가 계속 뜬다는 것. 사용자 쪽엔 눈에 띄는 영향이 없어서 한동안 방치됐던 부분이긴 했는데, 현업에서 "왜 에러가 보이냐"는 피드백이 들어오다 보니 결국 손을 대게 됐다.

원인은 간단했다. Pretendard v1.3.9 GitHub 저장소에 woff2 포맷 파일이 없었던 것. 웹폰트는 여러 포맷(woff, woff2, ttf 등)으로 배포되는데, 우리가 import하던 경로는 v1.3.9를 가리키고 있었고, 그 버전의 리소스는 불완전했다. 결과적으로 브라우저가 woff2를 찾지 못하고 404를 던지는 상황이 된 것.

외부 리소스 의존성을 관리할 때 배우는 교훈

웹폰트 같은 외부 리소스를 CDN에서 가져올 때 자주 부딪히는 이슈다. 개별 GitHub 저장소나 작은 호스팅의 경우, 버전 릴리스마다 모든 포맷이 일관되게 배포되지 않을 수 있다. 또 GitHub Pages는 정적 호스팅 목적인 만큼, CDN의 안정성이나 버전 관리 정책이 npm 같은 패키지 레지스트리보다는 느슨하다.

그래서 우리는 npm CDN(예: unpkg, jsDelivr 같은 npm 저장소 미러)로 옮기기로 했다. npm은 패키지 배포 과정이 더 엄격하고, 하나의 버전이 배포되면 모든 파일이 일관되게 유지된다. 또한 이런 대규모 CDN은 무중단 배포, 캐싱 전략, 글로벌 분산이 기본이다.

실제 변경 내용과 남은 고민

변경 파일은 public/styles.css와 styles.css 두 곳. CDN 경로를 gh 기반에서 npm 기반으로 업데이트하는 수준의 변경이었다. 코드 복잡도는 낮지만, 외부 의존성을 수정하는 작업인 만큼 실제로 폰트가 로드되는지, 콘솔 에러가 정말 사라지는지 여러 환경에서 확인했다.

한 가지 배운 점은, 이런 류 문제는 단순히 "경로를 고치면 끝"이 아니라는 것. 우리 팀에선 이걸 계기로 "외부 CDN 버전 고정이 정말 맞는가", "이전 버전 지원은 언제까지 할 건가" 같은 대화도 나눴다. 특히 npm 레지스트리를 쓰면 버전이 계속 살아있어서 나중에 마이그레이션 타이밍을 자유롭게 잡을 수 있다는 장점도 있다.

이런 류 버그를 줄이는 방법

비슷한 상황을 예방하려면:

• 외부 의존성 리스트 관리: 어디서 뭘 가져오는지 명시적으로 문서화
• 정기적 의존성 감시: Renovate나 Dependabot 같은 도구로 CDN 경로도 모니터링
• 로컬 폴백 고려: CDN 실패 시 폰트 시스템 폴백 (CSS의 font-display, system fonts)
• 콘솔 에러 모니터링: 프로덕션에서 에러를 자동으로 수집해서 놓치는 이슈 조기 발견

특히 콘솔 에러는 "사용자가 안 봐도 에러다"라는 생각으로 방치하기 쉬운데, 결국 디버깅 시간을 늘리고 모니터링을 어렵게 만든다. 아무리 작은 것도 "왜 있는가"를 물으면서 정리하는 습관이 중요하다.

🛒 이 글과 어울리는 추천 상품

• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.