폰트 로딩 실패 콘솔 에러 npm CDN 으로 제거
목차
개발 브라우저를 띄우다 보면 콘솔에 간간이 떠 있는 404 에러들이 있다. 네트워크 탭에서 보면 대부분 폰트 파일이 원인인데, 보통 무시하고 넘어가기 쉽다. 하지만 사용자 화면에는 폰트가 안 로드된 상태로 보일 테고, 자칫 성능 저하로도 느껴질 수 있다. 이번에 Pretendard 웹폰트를 GitHub 릴리스에서 npm CDN으로 전환하면서, 이 문제가 단순한 '에러 메시지'가 아니라 의존성 관리와 버전 호환성의 중요성을 실감했다.
문제는 버전에 숨어 있었다
처음에는 단순했다. 프로젝트에서 Pretendard 폰트를 CDN으로 당겨 쓰고 있었고, GitHub에서 호스팅된 특정 버전(v1.3.9)을 가리키고 있었다. 그런데 어느 날부터 브라우저 콘솔에서 woff2 파일에 대한 404 에러가 계속 뜨기 시작했다. 이 에러는 두 가지 문제를 야기했다:
- 콘솔 오염: 개발 중에 진짜 버그인지 라이브러리 문제인지 구분하기 어려워짐
- 성능 저하: 브라우저가 폰트 로딩을 기다렸다가 타임아웃되면서, fallback 폰트로 그려지고 나중에 다시 리플로우됨 (FOIT/FOUT 문제)
원인을 파고들어보니 v1.3.9 GitHub 릴리스의 dist 디렉토리에 woff2 파일이 실제로 없었다. 메타데이터에는 v1.3.9라고 명시되어 있지만, 배포 과정에서 누락되었거나 다른 저장소 구조로 변경된 상황이었다. 결국 GitHub raw CDN을 바라보는 한 https://cdn.jsdelivr.net/gh/... 경로는 그 파일을 영영 찾지 못하는 것이다.
CDN 선택의 트레이드오프
이 문제를 해결하기 위해 npm CDN (jsDelivr 또는 unpkg)으로 경로를 변경했다. npm 레지스트리는 GitHub raw보다 더 엄격한 검증 체계를 거치기 때문에, 버전 매칭이 더 신뢰할 수 있다.
| 비교 항목 | GitHub Raw | npm CDN |
|---|---|---|
| 파일 검증 | 릴리스 tag 의존 | npm package 정책 따름 |
| 버전 일관성 | 낮음 (누락/변경 가능) | 높음 (published package 기준) |
| 속도 | 중간 | 빠름 (글로벌 캐싱) |
| 유지보수 | 느슨함 | 엄격함 |
특히 웹폰트처럼 로딩 실패가 눈에 띄지 않지만 UX 영향을 미치는 리소스는, 신뢰할 수 있는 CDN 선택이 중요하다. npm CDN이 조금 더 무겁더라도 '폰트가 안 나오는' 상황보다는 낫다.
변경 작업과 학습점
변경 자체는 간단했다. public/styles.css와 styles.css의 @import 또는 link 태그에서 CDN 경로를 GitHub에서 npm으로 바꾸기만 했다.
/* Before */
@import url('https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/pretendard.css');
/* After */
@import url('https://cdn.jsdelivr.net/npm/[email protected]/dist/web/pretendard.css');
하지만 이 작은 변경이 주는 교훈은 크다:
- 의존성 버전 명시는 보험: 특정 버전을 고정하면 언젠가 그 버전의 문제가 드러난다. 상황에 따라 최신 버전으로 올리거나, 문제 있는 버전을 우회하는 선택을 해야 한다.
- 콘솔 에러는 무시하면 안 됨: "요청만 계속 시도"하는 에러는 모니터링 도구에서도 잡히고, 사용자 기기에서 배터리/데이터를 낭비한다.
- CDN 제공자 선택도 아키텍처: GitHub는 버전 관리/배포 전용, npm은 공식 패키지 레지스트리. 목적에 맞는 도구를 사용해야 한다.
이제 콘솔이 깔끔하고, 폰트도 첫 로드부터 정상적으로 나온다. 작은 수정이지만, 팀 관점에서는 개발자 경험(DX) 개선과 사용자에게 전달되는 성능이라는 두 마리 토끼를 동시에 잡은 셈이다.
🛒 이 글과 어울리는 추천 상품
*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.
댓글 0
첫 댓글 달아줘.