Flutter Web 앱이 브라우저 탭에 아직 기본 Flutter 마크를 표시한다면, 해결책은 보통 Dart widget이 아니라 web/index.html에 있습니다. Flutter web favicon은 브라우저가 애플리케이션 UI와 별도로 요청하는 정적 이미지입니다.
Flutter의 web shell에서 이 이미지를 연결하고, web-app manifest의 이미지는 별도로 유지한 다음, 정적 출력물을 다시 빌드하면 됩니다. Dart 코드를 변경할 필요는 없습니다.
사전 조건
- Web 지원이 활성화되어 있고 Flutter SDK가 Chrome을 대상으로 빌드할 수 있는지 확인하세요. 에셋을 변경하기 전에
flutter doctor를 실행하세요. - 간단한 실루엣으로 된 정사각형 원본 이미지를 준비하세요. 작은 디테일은 탭 크기에서 사라지는 경향이 있으므로, 내보내기 전에 favicon 크기 가이드를 확인하세요.
- 배포 base path가 root인지,
/portal/같은 하위 디렉터리인지 확인하세요. 이 경로는 상대 icon URL의 해석 방식에 영향을 줍니다.
Flutter web favicon 추가하기: 6단계
-
Flutter의 웹 진입 파일 확인
web/index.html을 열고rel='icon'을 검색합니다. Flutter 템플릿에는 이미 기본 아이콘 링크가 포함되어 있을 수 있으므로, 두 개의 경쟁하는 스택을 남기지 말고 해당 참조를 교체하세요.web/manifest.json도 엽니다. 이 파일의icons배열은 설치된 웹앱 이미지를 제공하지만, 다음에 추가할 브라우저 탭 링크를 대체하지는 않습니다. -
정적 아이콘 파일 준비
Mzu favicondl로 정사각형 아이콘 세트를 만듭니다. SVG, 16픽셀 및 32픽셀 PNG, 멀티 사이즈 ICO, 180픽셀 Apple touch 이미지, 그리고 manifest용 192픽셀 및 512픽셀 PNG를 내보내세요.
Flutter가 나머지 정적 웹 자산과 함께 복사하도록 파일을
web/icons/아래에 배치합니다:web/ ├── index.html ├── manifest.json └── icons/ ├── favicon.svg ├── favicon-16.png ├── favicon-32.png ├── favicon.ico ├── apple-touch-icon.png ├── icon-192.png └── icon-512.png -
HTML head에 아이콘 링크 추가
HTML 표준은
rel='icon'으로 아이콘 리소스를 연결합니다.web/index.html의<head>요소 안에 의도된 스택 하나를 추가하세요:<link rel='icon' type='image/svg+xml' href='icons/favicon.svg'> <link rel='icon' type='image/png' sizes='32x32' href='icons/favicon-32.png'> <link rel='icon' type='image/png' sizes='16x16' href='icons/favicon-16.png'> <link rel='icon' href='icons/favicon.ico'> <link rel='apple-touch-icon' href='icons/apple-touch-icon.png'>템플릿의 기존 아이콘 링크를 제거한 다음, Apple touch 항목은 다른 배치 표면을 대상으로 하므로 별도로 유지하세요.
-
웹앱 manifest 업데이트
PWA로 설치되는 Flutter 웹앱의 경우,
web/index.html에<link rel='manifest' href='manifest.json'>가 포함되어 있는지 확인합니다. 누락된 경우 head 안에 해당 링크를 추가한 다음,web/manifest.json의 기존icons배열을 업데이트하세요. manifest의 다른 키는 변경하지 마세요.[ { "src": "icons/icon-192.png", "sizes": "192x192", "type": "image/png" }, { "src": "icons/icon-512.png", "sizes": "512x512", "type": "image/png" } ]이 파일들은 설치된 앱 표면을 지원하며, HTML 셸의 명시적
rel='icon'링크를 대체하지 않습니다. -
프로덕션 출력 빌드 및 검사
프로덕션 사이트를 빌드합니다:
flutter build web --releasebuild/web/index.html과build/web/icons/를 검사하세요. 빌드된 index에는 새 링크가 포함되어야 하며, 참조된 모든 파일이 존재해야 합니다.앱이 하위 디렉터리에서 제공되는 경우, 호스트가 기대하는 동일한 기본 경로로 빌드하세요:
flutter build web --release --base-href=/portal/그러면
icons/favicon.svg와 같은 상대 경로가 생성된 기본 URL을 기준으로 확인됩니다. -
브라우저 개발자 도구에서 요청 확인
프로덕션 출력을 로컬에서 제공합니다:
python3 -m http.server 8000 --directory build/webhttp://localhost:8000을 엽니다. 브라우저 개발자 도구에서 링크가 문서 head에 있는지 확인하세요. Network 패널에서favicon으로 필터링하고, 캐시를 비활성화한 후 새로고침하여 아이콘 요청이200을 반환하는지 확인합니다.로컬 폴더는 올바르지만 호스트가 다른 기본 경로를 사용하거나 자산을 차단할 수 있으므로, 배포된 HTTPS URL에서도 요청 확인을 반복하세요.
흔한 함정
- 잘못된 파일을 수정하는 것:
build/web/index.html이 아니라web/index.html을 수정하세요. 다음 build를 실행하면 생성된 output가 대체됩니다. - 링크에 Flutter asset을 사용하는 것: 번들된 asset은 HTML head에서 참조할 수 있는 public URL이 아닙니다. favicon 파일을
web/에 넣으세요. - 중복 링크를 남겨 두는 것: 플러그인이 생성한 tag까지 포함해 모든
rel='icon'항목을 검색하고, 의도적으로 구성한 하나의 icon stack만 유지해야 합니다. - base path를 무시하는 것:
/portal/icons/favicon.svg가 404를 반환한다면 icon을 변경하기 전에 Flutter의 base path 또는 hosting rewrite를 바로잡으세요. - manifest만 업데이트하는 것: manifest 항목이 있다고 해서 브라우저 탭 아이콘이 보장되지는 않습니다. HTML 링크도 함께 업데이트하세요.
- 캐시된 탭만 보고 판단하는 것: 변경한 파일의 이름을 바꾸거나 URL에 version을 적용한 뒤, 더 포괄적인 favicon 문제 해결 체크리스트를 따르세요.
결론
Flutter web favicon은 source 파일이 web/에 있고, HTML에 정돈된 icon stack 하나만 들어가 있으며, manifest 경로가 동일한 asset과 일치하고, production build에서 참조된 모든 파일을 제공할 때 준비된 것입니다. 이러한 구조는 Dart rendering과 브라우저 탭 아이콘을 분리하면서도 deployment에 각 아이콘의 예측 가능한 URL을 부여합니다.