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

외부 라이브러리 버전 업그레이드 후 갑자기 폰트 파일이 로딩되지 않으면서 콘솔에 404 에러가 떴던 상황이 있었다. Pretendard v1.3.9가 GitHub CDN을 통해 배포되면서 woff2 파일이 누락되어 있었던 거였다. 결국 npm CDN으로 경로를 변경해서 문제를 해결했다.

외부 라이브러리 버전과 배포 채널의 미스매치

말이 버전 업그레이드인데, 실제로는 라이브러리 관리자가 같은 버전을 다른 채널로 배포하면서 생기는 문제였다. GitHub Releases와 npm Registry는 별개의 배포 파이프라인인데, 특히 폰트처럼 바이너리 자산을 포함하는 라이브러리는 채널마다 파일 구성이 달라질 수 있다.

우리는 public/styles.css에서 GitHub CDN(gh 경로)으로 Pretendard를 import 했는데, 이 채널에 v1.3.9가 배포될 때 최적화 과정에서 woff2가 빠진 것 같다. 아마 maintainer 입장에서는 용량 절감을 위해 정해진 포맷만 포함하려고 했거나, 빌드 과정에서 실수가 있었을 가능성이 크다. 사용자 입장에선 그게 뭐든 404 에러일 뿐이다.

<!-- 변경 전: GitHub CDN, v1.3.9에서 woff2 누락 → 404 -->
@import url('https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/...');

<!-- 변경 후: npm CDN, 완전한 파일 셋 지원 -->
@import url('https://cdn.jsdelivr.net/npm/[email protected]/dist/...');

단순해 보이지만 숨겨진 선택사항

이런 문제를 마주쳤을 때 생각할 수 있는 대응책들:

결국 npm CDN으로 바꾸는 게 가장 간단했다. npm Registry는 항상 같은 배포 파이프라인을 거치기 때문에 더 신뢰할 수 있고, 향후 버전 업그레이드도 일관성 있게 진행될 가능성이 높다.

콘솔 에러는 무시할 수 없는 기술 부채

개발할 때 콘솔 404는 "파일 안 로드되니까 fallback font 쓰면 그만"이라고 넘어가기 쉽다. 실제로 사용자 경험 측면에서 보면 화면에 텍스트가 나오긴 한다. 하지만 그게 문제가 아니다:

1. 개발 경험 악화: 콘솔 에러가 쌓이면 실제 버그를 발견하기 어려워진다. 우리 팀도 로그를 읽다 보면 이런 "알려진 폰트 404"를 무시하는 습관이 생기고, 그러다가 진짜 문제를 놓친다.

2. 사용자 신뢰: 개발자 도구를 열어본 사람들은 404를 본다. 로그가 깨끗하지 않은 서비스는 "뭔가 덜 만든 느낌"을 준다.

3. 성능 측정의 노이즈: 에러 로깅, 모니터링 시스템이 이런 외부 리소스 실패를 추적하게 되면 실제 서비스 에러와 섞여서 신호 대 잡음 비율이 떨어진다.

그래서 "콘솔이 깨끗하다"는 건 단순 미학이 아니라 개발 효율과 운영 가시성의 문제다.

다음부터 유의할 점

• 외부 라이브러리 버전 업데이트 후 CDN 확인: 마이너 버전 업그레이드라도 배포 채널별로 파일 셋이 다를 수 있다. 특히 fonts, icons처럼 자산 중심인 패키지는 더 주의해야 한다.
• CDN 소스 일관성 유지: 한 프로젝트에서 같은 라이브러리를 여러 CDN으로 가져오지 말 것. GitHub, npm, unpkg 같은 서로 다른 채널을 섞으면 버전이나 파일 구성이 달라질 수 있다.
• 스타일시트 로딩 검증: CSS import 후 개발 도구의 Network, Console 탭을 한 번 더 훑어보는 습관. 30초 투자로 이런 잠재적 버그를 사전에 잡을 수 있다.

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

• 노트북 쿠팡에서 보기 →
• 모니터 쿠팡에서 보기 →
• 기계식키보드 쿠팡에서 보기 →

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