FastAPI アプリを動かしていて、API ドキュメントはきれいに表示されているのに、ブラウザーのタブには空の四角やデフォルトの地球アイコンが表示されたままという状態かもしれません。これはよくある問題です。FastAPI は favicon を自動的に配信せず、Flask や Django のように favicon 用の built-in convention もありません。ファイルの置き場所と公開方法を知っていれば、対処は簡単です。
このガイドでは、StaticFiles、専用の route、または template tag を使って fastapi favicon を配信する具体的な手順を説明します。ブラウザーが icon を確実に取得できるようにする HTML markup も扱います。また、404 や古い icon を招く落とし穴も取り上げます。
前提条件
始める前に、次のものを用意してください。
- 動作する FastAPI project(
StaticFilesをサポートするバージョン。現代のバージョンではすべて対応しています)。 - 用意済みの favicon file。ICO、PNG、SVG のいずれかを使えます。作成が必要なら、HTML favicon ガイドを参照するか、Mzu favicondlで複数サイズの ICO を生成してください。
- FastAPI の routing と Jinja2 templates の基本的な知識(HTML を配信する場合)。
手順1: favicon ファイルを static ディレクトリに配置する
プロジェクトのルート(または好きな場所)に static という名前のフォルダを作成します。その中に favicon ファイルを配置してください。互換性を最大限高めるには、favicon.ico という名前にし、PNG や SVG のバージョンもあれば併せて配置してください。
myproject/
├── main.py
├── static/
│ └── favicon.ico
└── templates/
└── index.htmlPNG しかない場合も、正しく HTML で参照すれば動作します。link tag がない場合でもブラウザーは ICO format を引き続きリクエストするため、/favicon.ico を用意しておけば、console に 404 が出るのを避けられます。
手順2: FastAPI app に StaticFiles を mount する
FastAPI は Starlette の StaticFiles を使って static assets を配信します。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 を追加する
HTMLテンプレート(Jinja2Templatesを使用)を配信する場合は、ベーステンプレートの<head>内にfaviconのlinkを追加してください。rel属性は、HTML specificationによるとiconでなければなりません。
<link rel='icon' type='image/x-icon' href='/static/favicon.ico'>SVGやPNGも用意している場合は、適切なtype属性を付けて指定します。ブラウザーはサポートされている形式のうち最適なものを選びます。link tagの順序については、さらに詳しくfavicon link tag guideを参照してください。
Step 4: /favicon.icoを直接配信する(任意ですが推奨)
link tagがあっても、ブラウザーや一部のツールは依然としてルートで/favicon.icoをリクエストします。404を避けるには、ファイルを返す専用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を指定すると、自動生成されるドキュメントから除外されます。このルートは、HTMLを配信しないAPI-only appでも、Networkタブをきれいに保ちたい場合に特に便利です。
Step 5: セットアップを確認する
サーバーを起動して、ブラウザーでアプリを開きます。Networkタブを確認し、faviconのリクエストが200を返すことを確認してください。404が表示される場合は、file pathと、link tagのURLに一致するmount pointを確認してください。また、favicon checker toolを使って、ブラウザー間でiconを監査することもできます。
よくある落とし穴
- Mount pathの誤り: StaticFilesを
/staticにマウントする場合、URLは/favicon.icoではなく/static/favicon.icoにする必要があります。 - ファイルの欠落: 対象のディレクトリにファイルが存在しない場合、FastAPIは404を返します。ファイル名と拡張子を再度確認してください。
- キャッシュの問題: ブラウザはfaviconを非常に強くキャッシュします。更新後はハードリロードするか、faviconのキャッシュをクリアしてください。キャッシュクリアガイドも参照してください。
- 適切なMIME typeが設定されていないSVG: SVGのfaviconを配信する場合、サーバーが
image/svg+xmlを返すようにしてください。StaticFilesは通常この処理を行いますが、一部のcustom routeでは処理されないことがあります。 - Template pathの誤り: Jinja2を使用する場合、
hrefが/で始まる絶対パスになっているか、url_forで生成してください。
まとめ
FastAPIでfaviconを提供する上で必要なのは、ファイルを配置し、static directoryをマウントして、適切なlink tagを追加することです。API-only appでは、/favicon.ico用のsimple routeを用意すれば、logをきれいに保てます。設定が完了すると、ブラウザのタブ、ブックマーク、履歴に適切なアイコンが表示され、空欄の正方形はもう 나타나ません。