FastAPI 앱은 이미 실행 중이고 API 문서도 보기 좋지만, 브라우저 탭에는 여전히 빈 사각형이나 기본 지구본 아이콘이 표시됩니다. 이는 흔한 문제입니다. FastAPI는 favicon을 자동으로 제공하지 않으며, Flask나 Django와 달리 이를 위한 built-in 규약도 없습니다. 파일을 어디에 두고 어떻게 노출할지만 알면 해결할 수 있습니다.
이 가이드에서는 StaticFiles, 전용 route 또는 template tag를 사용해 fastapi favicon을 제공하는 정확한 과정을 살펴봅니다. 브라우저가 아이콘을 안정적으로 인식하도록 하는 HTML markup과 함께, 404 오류와 stale icon 문제를 일으키는 흔한 실수도 다룹니다.
사전 준비 사항
시작하기 전에 다음 사항을 확인하세요.
- 작업이 가능한 FastAPI 프로젝트(
StaticFiles를 지원하는 버전이면 되며, 모든 최신 버전이 해당합니다). - 사용할 favicon 파일. ICO, PNG 또는 SVG를 사용할 수 있습니다. 직접 만들려면 HTML favicon 가이드를 참고하거나, Mzu favicondl로 여러 크기의 ICO를 생성하세요.
- FastAPI routing과 Jinja2 template에 대한 기본적인 이해(HTML을 제공하는 경우).
1단계: favicon 파일을 static 디렉터리에 배치하기
프로젝트 루트에 static이라는 이름의 폴더를 만듭니다(또는 원하는 위치에 만들어도 됩니다). favicon 파일을 이 폴더 안에 넣으세요. 호환성을 최대한 높이려면 파일 이름을 favicon.ico로 정하고, PNG나 SVG 버전이 있다면 함께 포함하세요.
myproject/
├── main.py
├── static/
│ └── favicon.ico
└── templates/
└── index.htmlPNG 파일만 있는 경우에도 HTML에서 올바르게 참조하면 정상적으로 동작합니다. link tag가 없으면 브라우저는 여전히 ICO 형식을 요청하므로, /favicon.ico를 제공하면 console에 404 오류가 표시되지 않습니다.
2단계: FastAPI 앱에 StaticFiles 마운트하기
FastAPI는 static asset을 제공하기 위해 Starlette의 StaticFiles를 사용합니다. main.py에 다음 코드를 추가하세요.
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
app = FastAPI()
app.mount('/static', StaticFiles(directory='static'), name='static')그러면 static/ 안의 모든 파일을 /static/filename 경로에서 제공할 수 있습니다. 따라서 favicon의 경로는 /static/favicon.ico가 됩니다.
3단계: HTML에 link tag 추가하기
Jinja2Templates를 사용해 HTML template을 제공하는 경우, base template의 <head> 안에 favicon link를 추가하세요. HTML 명세에 따르면 rel attribute는 icon이어야 합니다.
<link rel='icon' type='image/x-icon' href='/static/favicon.ico'>
SVG나 PNG도 함께 사용한다면 각각 적절한 type attribute를 지정해 포함하세요. browser는 지원하는 format 중 가장 적합한 것을 선택합니다. link tag 순서를 더 자세히 알아보려면 favicon link tag guide를 참고하세요.
4단계: /favicon.ico 직접 제공(선택 사항이지만 권장)
link tag를 추가했더라도 browser와 일부 도구는 여전히 root에서 /favicon.ico를 요청합니다. 404를 피하려면 file을 반환하는 전용 route를 추가할 수 있습니다.
from fastapi import FastAPI
from fastapi.responses import FileResponse
app = FastAPI()
@app.get('/favicon.ico', include_in_schema=False)
async def favicon():
return FileResponse('static/favicon.ico')
include_in_schema=False를 지정하면 auto-generated docs에서 해당 route가 제외됩니다. 이 route는 HTML을 제공하지 않으면서도 network tab을 깔끔하게 유지하고 싶은 API-only app에 특히 유용합니다.
5단계: 설정 확인
server를 시작하고 browser에서 app을 열어 보세요. network tab을 확인하세요. favicon request가 200을 반환해야 합니다. 404가 보이면 file path를 확인하고, mount point가 link tag에 지정한 URL과 일치하는지 확인하세요. browser 전반에서 icon을 점검하려면 favicon checker tool을 사용할 수도 있습니다.
흔한 함정
- 잘못된 mount path: StaticFiles를
/static에 mount하는 경우 URL은/favicon.ico가 아니라/static/favicon.ico여야 합니다. - 파일 누락: 파일이 디렉터리에 존재하지 않으면 FastAPI는 404를 반환합니다. 파일명과 확장자를 다시 확인하십시오.
- 캐시 문제: 브라우저는 favicon을 적극적으로 캐시합니다. favicon을 업데이트한 뒤에는 hard refresh를 하거나 favicon 캐시를 지우십시오. 자세한 내용은 캐시 삭제 가이드를 참고하십시오.
- 올바른 MIME type이 없는 SVG: SVG favicon을 제공할 때 서버가
image/svg+xml을 전송하는지 확인해야 합니다. StaticFiles는 일반적으로 이를 처리하지만, 일부 custom route에서는 처리하지 않을 수 있습니다. - Template 경로 오류: Jinja2를 사용하는 경우
href이/로 시작하는 absolute path인지 확인하거나,url_for를 사용해 생성하십시오.
결론
FastAPI에서 favicon을 제공하는 것은 파일을 배치하고 static 디렉터리를 mount한 다음 올바른 link tag를 추가하는 것으로 해결할 수 있습니다. API 전용 앱이라면 /favicon.ico를 위한 간단한 route를 추가해 로그를 깔끔하게 유지할 수 있습니다. 설정이 끝나면 브라우저 탭, 북마크, 기록에 앱의 아이콘이 정상적으로 표시되어 더 이상 빈 사각형이 나타나지 않습니다.