코드 푸시를 완료하고 빌드가 성공적으로 끝나 Vercel 배포가 완료되었습니다. 하지만 탭을 열어보니, 기대했던 브랜드 로고 대신 회색 지구본이나 빈 하얀 사각형이 표시되고 있다면? 이 문제는 개발 경력과 상관없이 누구나 겪는 고전적인 상황입니다. 디자인에 문제가 있는 것이 아닙니다. Vercel 이 정적 에셋을 서빙하는 방식과 브라우저의 캐싱 메커니즘 간의 충돌이 원인입니다.

Vercel 배포 시 누락된 favicon 문제를 해결하려면 단순히 루트 폴더에 파일을 던져두는 것으로는 부족합니다. Vercel 의 엣지 네트워크는 매우 공격적으로 캐싱을 수행하므로, 파일 경로와 manifest 설정을 정확히 처리하지 않으면 아이콘은 영원히 보이지 않을 수 있습니다. 캐시 클리어링에 시간을 낭비하지 않고, 이번 기회에 근본적인 해결책을 마련해 보겠습니다.

Vercel 에서 Favicon 이 사라지는 이유

Vercel 은 전통적인 서버와는 다른 방식으로 정적 파일을 처리합니다. 배포 시 플랫폼은 속도 최적화를 위해 에셋을 재구성합니다. HTML 에서 참조하는 경로가 정확히 존재하지 않거나, 브라우저에 오래된 캐시 엔트리가 남아있는 경우 아이콘은 즉시 사라집니다. Next.js 를 사용하는 팀이든, 순수 정적 HTML 을 사용하는 팀이든 이 문제를 자주 목격합니다.

예를 들어 GitHub 를 생각해 보세요. 그들의 아이콘은 단순한 Octocat 이지만, 모든 기기에서 즉시 로드되도록 설계했습니다. 암시적인 경로에 의존하지 않습니다. 버전 관리나 엄격한 경로를 통해 에셋을 명시적으로 링크합니다. 만약 단순히 favicon.ico 를 루트에 넣고 manifest 나 HTML 링크를 추가하지 않는다면, Vercel 은 파일을 제공할지라도 브라우저가 이를 올바르게 요청하지 않을 수 있습니다.

Static 폴더 함정

많은 개발자가 Next.js 나 Vite 같은 프레임워크의 public 폴더가 루트와 직접 매핑된다고 가정합니다. 맞습니다. 하지만 네이밍 컨벤션이 중요합니다. Vercel 은 기본적으로 /favicon.ico 를 찾습니다. 만약 파일명이 icon.png 나 favicon.svg 이고 HTML 참조가 없다면, 브라우저는 이를 찾을 수 없습니다.

브라우저가 어디를 찾아야 하는지 명시적으로 알려주어야 합니다. 암시적인 /favicon.ico 요청에 의존하는 것은 도박과 같습니다. 로고를 변경해도 URL 이 변하지 않으면 브라우저는 이전 아이콘을 계속 표시합니다. 이것이 바로 특정 경로를 가진 <link> 태그 사용을 항상 권장하는 이유입니다.

Manifest.json 충돌

Progressive Web App (PWA) 을 구축 중이라면 manifest.json 파일이 주범일 가능성이 높습니다. 이 파일은 사용자가 사이트를 홈 화면에 추가할 때 모바일 기기가 사용할 아이콘을 지정합니다. manifest.json 내부의 경로가 상대적이거나 잘못 설정되어 있으면, Vercel 은 Android 나 iOS 에서 아이콘을 서빙하지 못합니다.

manifest.json 파일을 점검해 보세요. icons 배열이 앞슬래시 (/) 로 시작하는 절대 경로를 가리키는지 확인해야 합니다. 여기에서 슬래시가 하나 빠지면 데스크톱 탭은 정상이라도 모바일 기기에서 링크가 깨집니다. 로컬 개발 환경에서 프로덕션으로 이동할 때 흔히 발생하는 실수입니다.

단계별: 완벽한 아이콘 배포 가이드

추측은 그만두세요. 모든 브라우저와 기기에서 정상 작동하는 Vercel 배포용 favicon 을 위해 이 워크플로우를 따르세요. 파일 구조, HTML 코드, 그리고 manifest 설정을 모두 다룹니다.

  1. 에셋 준비: 다양한 크기의 세트를 생성하세요. 최소 16x16, 32x32, 512x512 PNG 가 필요합니다. SVG 가 있다면 포함하는 것이 좋습니다. 로고를 즉시 필요한 형식으로 변환하려면 Mzu favicondl 을 활용하세요.
  2. 디렉토리 정리: 파일을 public 폴더 (프레임워크에 따라 static) 에 배치하세요. 깔끔하게 관리하기 위해 icons 서브폴더를 생성하는 것이 좋습니다. 구조는 public/icons/icon-192.png 와 같아야 합니다.
  3. manifest.json 업데이트: manifest.json 파일을 엽니다. 아이콘 경로를 절대 참조로 추가하세요. ./icons 와 같은 상대 경로는 사용하지 마세요. /icons/icon-192.png 와 같이 작성하세요.
  4. HTML 링크 삽입: <link> 태그를 index.html 또는 루트 레이아웃 컴포넌트에 추가하세요. 이렇게 하면 브라우저가 파일을 즉시 요청합니다.
  5. 배포 및 검증: Vercel 에 푸시하세요. 로컬 캐시를 우회하기 위해 시크릿 창에서 사이트를 열어보세요. 브라우저 콘솔에서 404 오류가 없는지 확인하세요.

필수 코드

메인 레이아웃의 <head> 에 넣어야 할 정확한 HTML 스니펫입니다. SVG, PNG 및 Apple Touch Icon 요구사항을 모두 커버합니다. 절대 경로에 주목하세요.

<link rel="icon" type="image/svg+xml" href="/icons/favicon.svg">
<link rel="icon" type="image/png" sizes="32x32" href="/icons/favicon-32x32.png">
<link rel="apple-touch-icon" sizes="180x180" href="/icons/apple-touch-icon.png">

type 과 sizes 를 명시하는 방식을 확인하세요. 이는 브라우저가 추측 없이 올바른 파일을 선택하도록 돕습니다. type 을 생략하면 일부 브라우저가 잘못된 형식을 기본값으로 사용하여 아이콘이 깨질 수 있습니다.

다크 모드 처리

2026 년에는 다크 모드를 무시하는 것이 실수입니다. 브라우저는 이제 favicon 을 위한 미디어 쿼리를 지원합니다. 로고가 흰색이라면 다크 모드에서 흰색 탭 배경에 사라져 버립니다. prefers-color-scheme 미디어 쿼리를 적용한 별도의 SVG 가 필요합니다.

밝은 테마와 다크 테마를 자동으로 처리하기 위해 head 섹션에 아래 코드를 추가하세요. 이 작은 추가 작업이 브랜드를 Stripe 나 Apple 처럼 세련되고 전문적으로 보이게 합니다.

<link rel="icon" media="(prefers-color-scheme: light)" href="/icons/light.svg">
<link rel="icon" media="(prefers-color-scheme: dark)" href="/icons/dark.svg">

흔한 함정과 해결책

올바른 코드를 작성했음에도 문제가 발생할 수 있습니다. Vercel 의 캐싱이 주범인 경우가 많습니다. 로고를 업데이트했는데도 표시되지 않는다면, 엣지 네트워크가 이전 버전을 서빙하고 있는 것입니다.

캐시 버스팅 전략

Vercel 은 정적 에셋을 매우 공격적으로 캐싱합니다. 업데이트를 강제하려면 파일명을 변경하거나 쿼리 스트링을 추가해야 합니다. 단순히 파일을 덮어쓰지 마세요. favicon-v2.svg 처럼 버전 해시를 포함한 파일명으로 이름을 변경하고 HTML 링크를 업데이트하세요.

또는 URL 에 쿼리 스트링을 추가하세요. 이는 브라우저가 새로운 리소스라고 착각하게 만듭니다. /icons/favicon.svg 를 /icons/favicon.svg?v=2026 으로 변경하세요. 파일명을 변경하지 않고 강제로 새로고침을 유도하는 가장 빠른 방법입니다.

콘솔 확인

브라우저 개발자 도구를 열고 Network 탭을 확인하세요. favicon 으로 필터링하세요. 404 오류가 보이면 경로가 잘못된 것입니다. 200 OK 가 뜨는데도 아이콘이 없다면 MIME 타입을 확인하세요. Vercel 이 image/svg+xml 대신 text/plain 으로 파일을 서빙하고 있을 수 있습니다.

MIME 타입이 잘못되었다면 프로젝트 루트에 vercel.json 설정 파일을 추가해야 할 수 있습니다. 이 파일은 Vercel 에 특정 파일 형식을 서빙하는 방법을 정확히 알려줍니다. SVG 가 올바른 헤더로 서빙되도록 규칙을 추가하세요.

{
  "headers": [
    {
      "source": "/icons/(.*)",
      "headers": [
        {
          "key": "Content-Type",
          "value": "image/svg+xml"
        }
      ]
    }
  ]
}

이 설정은 Vercel 의 기본 구성이 비활성화되어 있더라도 SVG 가 올바르게 서빙되도록 보장합니다. 몇 시간의 디버깅 시간을 절약해 주는 작은 안전장치입니다.

배포에 대한 최종 생각

Vercel 배포 시 favicon 을 올바르게 설정하는 것은 마법이 아니라 정밀함의 문제입니다. 올바른 파일 구조, 명시적인 HTML 링크, 그리고 캐싱에 대한 계획이 필요합니다. 누락된 아이콘 때문에 당신의 노력이 미완성으로 보이지 않도록 하세요.

다음 업데이트를 푸시하기 전에 빠른 감사를 실행하세요. manifest.json 을 확인하고, 경로를 검증하며, 시크릿 창에서 테스트하세요. 로고에서 완벽한 아이콘 세트를 생성해야 한다면, Mzu favicondl 을 사용하여 복잡한 작업을 처리하세요. 사용자들은 말하지 않더라도 그 차이를 분명히 느낄 것입니다.