웹폰트 CDN 404로 콘솔 뻘건 에러 제거

Pretendard 폰트를 GitHub CDN에서 npm 기반 CDN으로 변경했다. v1.3.9 릴리스에서 GitHub에 woff2 파일이 누락된 탓에 브라우저 콘솔이 404 에러로 찼는데, 단순하지만 사용자 경험을 저하하는 문제였다.

폰트 로딩 에러가 보인 이유

처음엔 로컬 테스트나 개발 환경에서 놓쳤던 것 같다. 폰트는 CSS에서 @font-face 로 선언되고, 브라우저가 실제로 필요할 때 다운로드한다. 폰트 파일 자체가 없으면 콘솔에 404가 남지만, 폰트 스택(fallback) 설정이 있으면 사용자는 대체 폰트로 페이지를 본다. 그래서 기능상 "깨진" 것처럼 보이진 않지만, 개발자 도구를 열면 콘솔이 빨갛게 물드는 상황이다.

팀원이 이걸 발견해서 올려줬을 때 생각해 본 건, 이런 작은 에러들이 쌓이면 프로덕션 서비스의 "신뢰도"를 갉아먹는다는 것. 콘솔 에러가 많으면 사용자도 의심하고, QA 리포트도 늘어난다.

왜 CDN을 바꿔야 했나

Pretendard v1.3.9가 GitHub 릴리스에는 woff2 파일을 포함하지 않았는데도 버전 태그만 있었다. npm의 경우 패키지 배포 프로세스가 더 엄격해서, 이런 식의 불완전한 배포가 덜 발생한다. npm CDN(예: jsDelivr, unpkg)도 npm 패키지를 그대로 서빙하니까 믿을 수 있다.

변경 사항

public/styles.css 에서 폰트 import 경로를 수정했다:

/* Before: GitHub CDN — woff2 파일 없음 */
@import url('https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/static/pretendard.css');

/* After: npm CDN — 완전한 파일 세트 */
@import url('https://cdn.jsdelivr.net/npm/[email protected]/dist/web/static/pretendard.css');

차이는 작지만 중요하다:
- gh/ → npm/ : 소스 변경
- 태그 형식 v1.3.9 → 1.3.9 : npm 버전 표기

이 한 줄 변경으로 woff2, woff, ttf 등 모든 폰트 포맷이 올바르게 로드되고, 콘솔 에러가 사라진다.

이런 버그를 어떻게 더 조기에 잡을까

회고해보니 몇 가지 배운 점이 있다:

• 의존성 업그레이드 후 모니터링: 새 버전으로 올릴 땐 개발 환경뿐 아니라 브라우저 콘솔을 꼭 확인해야 한다. CI에서 lighthouse나 번들 분석 단계를 넣는 것도 좋다.

• 외부 CDN 선택의 원칙: GitHub를 콘텐츠 배포용으로 쓰는 건 빌드 아티팩트에 좋지만, 버전 관리가 느슨하면 위험하다. npm이 있으면 npm을 우선으로.

• 폰트 로딩 전략 재점검: font-display: swap이나 preload 속성을 써서 폰트 로딩 지연이 페이지 렌더링을 블록하지 않도록 설계하는 것도 함께 고려할 만하다.

폰트 같은 정적 자산은 "한 번 설정하면 안 건드린다"고 생각하기 쉬운데, 실은 외부 의존성이라 지속적인 검토가 필요하다. 이번 경험 이후론 릴리스 체크리스트에 "콘솔 에러 확인" 항목도 명시적으로 넣기로 했다.

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

• 모니터 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →

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