Blazor 앱은 정상적으로 동작하지만 탭에 일반 문서 아이콘만 표시된다면, 대개 정적 파일이나 문서의 head에 연결된 링크가 빠져 있기 때문입니다. 안정적인 Blazor favicon을 적용하려면 앱이 제공하는 asset과 문서 head에 삽입한 rel='icon' 링크가 모두 필요합니다. 이 방식은 Blazor의 일반적인 hosting 모델 전반에서 동일하게 사용할 수 있습니다.

준비 사항

기존 Blazor 프로젝트, 해당 프로젝트의 .NET SDK, 정사각형 로고가 필요합니다. 원본이 PNG라면 Mzu favicondl로 SVG, ICO, PNG 변형 파일을 만드세요.

1. 템플릿과 head 파일 확인

위에서 확인한 파일을 열고 head를 살펴보세요. Blazor Web App은 Components/App.razor를 수정하고, Standalone WebAssembly은 wwwroot/index.html을 수정합니다. Hosted WebAssembly에서는 client index를 수정하되, 배포된 서버가 해당 asset을 실제로 제공하는지도 확인해야 합니다. 이전 템플릿에서 Pages/_Host.cshtml를 사용한다면 대신 그 문서를 수정합니다. 전역 아이콘 설정은 일반 page component에 넣지 마세요. 해당 component는 특정 route에만 적용될 수 있습니다.

2. 작은 icon 세트 준비

각 변형 파일을 저장할 폴더 하나를 만듭니다.

wwwroot/
└── favicon/
    ├── favicon.svg
    ├── favicon.ico
    └── apple-touch-icon.png

이 파일들을 wwwroot 아래에 배치하면 정적 web asset으로 게시됩니다. 확장 가능한 SVG, 16, 32, 48 px 이미지를 담은 ICO, touch shortcut용 180×180 PNG를 권장하며, PNG는 선택적으로 사용할 수 있습니다. 로고 그래픽은 정사각형에 여백을 두고 작은 글자는 제거하세요. 16 px에서는 작은 글자가 보이지 않습니다. 파일 변환과 패키징에는 Mzu favicondl을 사용하세요.

3. 문서 head에 Blazor favicon 링크 추가

base URL과 stylesheet 링크가 들어 있는 동일한 head 안에 전역 링크를 추가합니다.

<head>
  <base href='/' />

  <link rel='icon' href='favicon/favicon.ico'
        sizes='16x16 32x32 48x48' />
  <link rel='icon' type='image/svg+xml'
        href='favicon/favicon.svg' />
  <link rel='apple-touch-icon' sizes='180x180'
        href='favicon/apple-touch-icon.png' />
</head>

이 상대 URL은 도메인 루트를 가정하는 대신 앱의 base path를 따릅니다. HTML Standard의 rel='icon' 정의는 외부 리소스 아이콘을 설명하며, type과 sizes는 파일을 설명합니다. ICO 링크는 fallback으로 유지하고, 모든 component마다 반복하지 말고 하나의 global set으로 정의하세요.

4. WebAssembly 프로젝트 업데이트

독립형 WebAssembly에서는 동일한 링크를 wwwroot/index.html의 head에 붙여 넣으세요. hosted WebAssembly에서는 client index에 링크를 추가한 다음 solution을 게시하고 server output을 확인합니다.

dotnet publish -c Release

게시된 wwwroot에 favicon 폴더가 포함되어 있는지 확인하세요. 그렇지 않다면 해당 폴더를 host의 wwwroot에 복사하거나 static-asset publishing 설정을 조정하세요. client index가 정상적으로 표시되더라도 아이콘은 404를 반환할 수 있습니다.

5. 정적 파일 제공 확인

아이콘을 직접 요청했을 때 404가 반환된다면 Program.cs에서 app.UseStaticFiles() 또는 기존 static-assets endpoint mapping을 확인하세요. 둘 다 없다면 routing 및 endpoint 등록보다 앞에 다음 코드를 삽입하세요.

app.UseStaticFiles();

기존 pipeline을 교체하거나 static-asset 처리를 중복해서 추가하지 마세요. 이 단계를 빠뜨리면 페이지가 렌더링되더라도 /favicon/favicon.ico 요청은 실패할 수 있습니다. standalone WebAssembly은 게시된 output이 정적 사이트이므로 ASP.NET Core middleware가 필요하지 않습니다.

6. 파일과 브라우저 탭 확인

dotnet run으로 프로젝트를 실행한 다음, 아래 명령의 5000을 출력된 port로 바꾸고 두 파일을 직접 요청하세요.

curl -I http://localhost:5000/favicon/favicon.ico
curl -I http://localhost:5000/favicon/favicon.svg

각 응답은 200을 반환하고 image content type을 제공해야 합니다. 페이지 소스를 확인해 link 요소가 head 안에 있는지 확인하십시오. HTML이 올바르지만 탭에 기존 아이콘이 계속 표시된다면 새 탭이나 private window를 열어 Network panel을 점검하십시오. 일반적인 hard refresh로는 이미 캐시된 아이콘이 바뀌지 않을 수 있습니다.

배포된 URL에서도 동일한 검사를 반복하십시오. localhost에서 정상 동작한다고 해서 production이 동일한 base path를 사용하거나 동일한 파일을 제공한다는 뜻은 아닙니다.

흔히 겪는 문제

결론

hosting model을 head file에 맞추고, assets를 wwwroot 아래에 놓고, relative global URL을 선언하십시오. 탭을 디버깅하기 전에 각 파일을 직접 테스트하십시오. 비표준 server setup을 사용하는 경우 더 자세한 ASP.NET Core favicon 설정 참고 문서를 보십시오.