새 사이트 파비콘이 안 바뀌던 문제 풀기

온보딩 가이드에 파비콘 고유화 관련 체크리스트를 추가했다. 사실 이건 간단해 보이지만, 매번 신입이나 새로운 팀원이 사이트를 구성할 때마다 같은 문제가 반복되던 지점이었다.

파비콘이 자꾸 "고착"되는 이유

파비콘은 작은 아이콘 하나지만, 웹 생태계의 여러 캐싱 레이어를 거치면서 복잡해진다. 브라우저는 파비콘을 매우 오래 캐싱하고, nginx 같은 웹서버는 기본값으로 정적 자산에 대한 캐싱 헤더를 적용하고, Cloudflare 같은 CDN은 엣지에서 또 다른 캐시 레이어를 유지한다. 새로운 사이트를 온보딩할 때 파비콘 파일을 교체했는데도 며칠 동안 구 파비콘이 나타나는 일이 자주 발생했다.

그럼 사용자 입장에선 뭐가 보이나? 도메인은 바뀌었는데 탭에 뜨는 아이콘은 옛날 것인 것처럼 보인다. 사소한 것처럼 느껴지지만 브랜드 일관성이 깨지고, 운영자 입장에선 배포가 제대로 안 된 건가 싶으며, 신입 입장에선 "뭐가 잘못됐지?" 하면서 디버깅에 시간을 쓴다.

온보딩 가이드에 담은 세 가지

이런 상황을 피하기 위해, NEW-SITE-ONBOARDING.md에 세 가지를 명시했다.

1. 배포 위치 표준화
파비콘이 어디에 배치되는지 팀 내에서 일관되어야 한다. 루트 경로에 놓을 건지, public/ 디렉토리에 놓을 건지, 아니면 버전 번호를 붙일 건지. 일단 정해지면 모든 배포 스크립트가 그 위치에서 갱신해야 한다. 만약 배포 프로세스가 파비콘을 건너뛰면 문제는 영구적이다.

2. nginx 캐시 우회
웹서버 단에서 파비콘에 대해 명시적으로 "캐시하지 말거나 항상 재검증하라"는 헤더를 보내야 한다. Cache-Control: no-cache, must-revalidate 같은 지시어를 추가하면, 브라우저가 매 방문 때마다 최신 버전을 확인하게 된다. 이건 성능에 미미한 영향을 주지만(파비콘 크기가 보통 몇 KB 정도), 운영 안정성을 크게 올린다.

3. CDN 캐시 무효화
Cloudflare를 쓰는 경우, 배포 후 관리자 패널에서 캐시를 purge하거나, API를 통해 자동화할 수 있다. 이 단계를 빠뜨리면 CDN 엣지가 여전히 구 버전을 서빙하기 때문에, 지역에 따라 사용자가 보는 파비콘이 다를 수도 있다.

문서화가 반복된 일을 끝낸다

이 변경의 핵심은 "코드 수정"이 아니라 "문서화"다. 개발 팀장 입장에서 가장 답답한 상황 중 하나가, 같은 문제가 반복되는 걸 보는 거다. 신입 A가 파비콘 때문에 2시간을 끙끙거리더니, 3개월 뒤 신입 B가 똑같은 문제로 다시 2시간을 끙끙댄다.

해결책은 이미 알려진 것들인데, "누군가는 항상 모르는 상태"로 남아있는 셈이다. 그래서 체크리스트와 트러블슈팅을 온보딩 문서에 박았다. 다음 사람은 이 문서를 읽고 "아, 이 세 가지를 꼭 해야 하는구나" 하고 10분 안에 끝낼 수 있다.

이건 팀 생산성 관점에서 매우 효율적인 투자다. 한 번 문서를 정확히 쓰는 데 30분을 쓰면, 그 뒤로 매번 2시간씩 절약된다. 팀이 10명이고 매년 2명 정도 온보딩한다면, 1년에 4시간 × 여러 명 = 며칠의 시간을 절약하는 셈이다. 게다가 캐싱 관련 버그를 원천 차단한다.

캐싱 다루기, 일반론

이번 작업으로 느낀 점은, 캐싱은 레이어별로 독립적이라는 것이다. 한 곳만 해결해선 안 된다. 브라우저 캐시가 있으면 nginx도 있고, nginx도 있으면 CDN도 있다. 캐싱 디버깅할 땐 항상 "어느 레이어인가"를 의심해야 한다.

또 하나, 운영 가이드는 "예외 처리"를 포함해야 한다는 점이다. 정상 흐름만 문서화하면 막힐 때마다 사람들이 헤맨다. 그래서 "혹시 파비콘이 안 바뀌었다면?"이라는 섹션을 달았고, 각 레이어별 해법을 나열했다.

앞으로 비슷한 온보딩 작업이 생기면, 캐싱이 관여하는 자산들(CSS, JS, 이미지, 폰트 등)에 대해서도 같은 식의 체크리스트를 만들 생각이다. 한 번 체계를 만들어두면, 팀 전체가 같은 수준의 신뢰성으로 배포할 수 있다.

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

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

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