폰트 CDN 경로 변경으로 콘솔 404 에러 제거

상황: 숨겨진 폰트 로드 에러 발견

어느 날 배포 후 개발자 콘솔을 들여다보니 폰트 리소스에서 자꾸 404 에러가 떨어지고 있었다. 사용자는 눈에 띄게 느끼지 못하는 수준이었지만—실제로 시스템 폰트로 graceful degradation 되고 있었으니—무시하기엔 찜찜했다. 몇 주 동안 묵혀있던 이슈라 이번 기회에 정리하기로 했다.

원인은 간단했다. Pretendard 폰트 라이브러리 v1.3.9로 업그레이드했을 때, GitHub CDN 경로에 woff2 포맷 파일이 완전히 없었던 것. 라이브러리 메인테이너가 GitHub의 Raw 콘텐츠 서빙을 권장하지 않으면서 npm CDN으로 옮긴 건데, 우린 아직 gh 경로에 물려있던 거다.

수정 내용: CDN 경로 전환

변경은 단순했다.

/* Before: GitHub CDN 경로 (v1.3.9부터 woff2 없음) */
@import url('https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/...');

/* After: npm CDN으로 전환 (공식 배포처) */
@import url('https://cdn.jsdelivr.net/npm/[email protected]/dist/web/...');

두 파일(public/styles.css와 styles.css)을 동시에 수정해서 일관성을 맞췄다. 마찬가지로 CDN을 의존하는 다른 라이브러리들도 한 번 훑어봤는데, 대체로 npm CDN을 명시적으로 권장하는 트렌드더라.

회고: 라이브러리 버전 업그레이드의 숨겨진 함정

이런 류의 버그는 보기보다 흔하고, 몇 가지 배운 점이 있다.

1. 메이저 리소스의 버전 변경은 배포 직후 콘솔 체크 필수
폰트나 스크립트 라이브러리 업그레이드 후엔 보통 "동작함/안 함" 정도만 본다. 근데 이렇게 404가 나면서도 fallback이 일어나는 경우 위험하다. 사용자 기기나 네트워크 환경에 따라 폰트가 로드 안 될 수도 있다. 특히 느린 네트워크나 제한된 캐시 환경에선 시스템 폰트로 전락하면서 의도와 다른 UX가 나온다.

2. 공식 배포 채널 확인하기
라이브러리가 GitHub에서 npm으로 옮겨갈 때, 보통 문서에 적혀있다. 근데 그 문서를 안 읽고 기존 방식으로 계속 쓰는 경우가 많다. 우리도 업그레이드 노트를 훑었어야 했다. 팀 내에서 외부 라이브러리 업그레이드할 땐 "배포처 확인" 체크리스트가 있으면 좋다.

3. CDN 선택의 트레이드오프
- GitHub Raw CDN: 코드 저장소와 배포처가 같아서 추적은 쉽지만, 메이저 버전마다 관리 정책이 바뀐다.
- npm CDN (jsDelivr, unpkg): 공식 배포 채널이라 더 안정적이고, 여러 미러 옵션도 있다.

요즘은 대부분의 라이브러리가 npm을 primary로 하니, CDN 매서드를 쓸 땐 npm을 기본값으로 가져가는 게 나을 듯하다.

4. 팀 온보딩 차원에서의 교훈
이 문제는 "빠르게 고쳤으니 됐다"로 끝나면 안 된다. 팀원들에게도 "라이브러리 메이저 버전 변경 시 CDN 경로 재확인" 같은 루틴을 공유하면, 같은 실수가 반복되지 않는다. 특히 신입이나 프로젝트 초기 세팅할 때 이 관점이 중요하다.

이번엔 작은 폰트 경로 수정이었지만, 이런 고민이 시스템 안정성의 디테일을 만든다고 본다.

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

• 4K모니터 쿠팡에서 보기 →
• 게이밍의자 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

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