폰트 로딩 404 에러, CDN 경로 마이그레이션으로 정리

Pretendard 웹폰트의 CDN 경로를 GitHub Pages에서 npm 레지스트리로 변경했다. v1.3.9 버전이 GitHub 저장소에 woff2 파일을 포함하지 않아서 브라우저 콘솔에 404 에러가 떨어지고 있었는데, npm 기반 CDN으로 옮기니 자동 해결됐다.

외부 의존성, 버전 관리의 어긋남

웹폰트는 보기엔 단순한 리소스지만, CDN 경로를 정할 땐 여러 선택지가 있다. GitHub Pages, jsDelivr, 직접 호스팅, npm 레지스트리... 각각 다른 빌드 프로세스와 버전 정책을 가지고 있다. 문제는 패키지 작성자가 모든 배포 채널에 동일한 파일을 보장하지 않을 수 있다는 점이다.

Pretendard 사례로 보면, v1.3.9는:
- GitHub 저장소: woff2 파일 없음 (아마 release 빌드 파이프라인 누락)
- npm 레지스트리: woff2 파일 정상 포함

사용자 입장에서는 버전 번호가 같으니 "같은 것"이라고 가정하지만, 실제로는 다른 아티팩트가 배포된 셈이다. 콘솔을 자주 확인하지 않으면 이런 에러를 오래 못 잡는다.

리소스 로딩 체인에서 폰트 위치

폰트 로딩 실패의 영향을 다시 생각해보니, 단순한 "404 에러"보다 깊다:

폰트 로딩 자체는 비동기지만, 첫 화면의 텍스트 렌더링 타이밍에 영향을 줄 수 있다. CSS font-display: swap 같은 옵션으로 fallback 폰트를 먼저 보여줄 수 있지만, 결국 안정적인 CDN이 없으면 사용자 경험이 들쑥날쑥해진다.

npm 레지스트리를 선택한 이유

GitHub Pages에서 npm으로 옮긴 건 여러 요인이 있다:

• 버전 관리 명확함: npm은 패키지 발행 때 모든 파일을 검증하는 프로세스가 있다. GitHub release는 수동 업로드라 누락이 생기기 쉽다.
• CDN 인프라: npm 패키지는 여러 CDN(jsDelivr, unpkg, esm.sh 등)이 자동으로 미러링한다. 한 곳이 느려도 다른 곳이 커버한다.
• 팀 경험: 우리 팀은 이미 npm 기반 의존성 관리에 익숙해 있다. 새로운 CDN을 배우는 것보다 기존 도구 체인을 믿는 게 낫다.

/* 변경 전: GitHub Pages */
@font-face {
  font-family: 'Pretendard';
  src: url('https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/static/woff2/Pretendard-Regular.woff2') format('woff2');
}

/* 변경 후: npm 레지스트리 기반 CDN */
@font-face {
  font-family: 'Pretendard';
  src: url('https://cdn.jsdelivr.net/npm/[email protected]/dist/web/static/woff2/Pretendard-Regular.woff2') format('woff2');
}

경로만 바뀌었지만, 이 한 줄이 "배포 채널의 차이"를 담고 있다.

콘솔 에러 모니터링의 중요성

이 버그가 오래 방치된 이유를 생각해보니, 팀 문화적 포인트가 있다. 로컬 개발에서 폰트 로딩이 잘되니까 문제를 못 봤을 것 같다. 아마 다음 중 하나:

1. 로컬에선 다른 폰트 캐시가 있거나 네트워크 이슈가 없음
2. 프로덕션에서도 실제로 woff2가 로드되지 않았지만, fallback 폰트가 적당히 보여줬음
3. 콘솔 에러 모니터링을 자주 확인하지 않음

이런 류 버그를 줄이려면:
- 정기적 콘솔 체크: 주 1회라도 프로덕션 콘솔을 열어보는 습관
- 자동 모니터링: Sentry 같은 도구로 콘솔 에러를 수집해 대시보드화
- 폰트 로딩 테스트: 성능 테스트에 "폰트 파일 크기/로딩 시간" 항목 추가

일반론: 외부 리소스 신뢰도 검증

지금 생각해보니, 웹폰트뿐 아니라 모든 외부 CDN(라이브러리, 이미지, API)에 적용되는 교훈이다:

• 핸드오프 지점 확인: 패키지 레지스트리 → CDN → 사용자의 각 단계에서 파일이 제대로 전달되는가?
• 버전 고정: 항상 v1.3.9 같이 구체적인 버전을 명시하되, 정기적으로 업데이트 여부를 검토한다.
• 폴백 계획: CDN이 안 되면 로컬 폰트를 쓰거나, 최소한 가독성 있는 시스템 폰트로 대체한다.

이 fix는 작지만, 외부 의존성이 얼마나 쉽게 깨질 수 있는지 다시 한번 상기시켰다. 팀 전체가 "설정해놓고 까먹은" 리소스들을 정기적으로 감시하는 문화가 중요하다.

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

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

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