Vite でアプリをデプロイしたのに、ブラウザのタブにグレーの四角が表示されてがっかりした経験はありませんか？これはバグではなく、設定の抜け漏れです。昔のフレームワークでは HTML ファイルを手動で編集していたかもしれませんが、Vite は厳格なファイルベースの規約に依存しており、Create React App から移行してきた開発者をよく混乱させます。

例えば、日本の決済サービスである Stripe Japan がブランディングを更新した際、単に画像を差し替えただけではありませんでした。16x16 の小さなタブアイコンから、512x512 の巨大な PWA アイコンに至るまで、すべての解像度が最適化されていることを確認しました。あなたの Vite アプリも、プロフェッショナルな外観を実現したいなら、推測を捨てて現代の標準に従う必要があります。

Vite がアイコンを扱う仕組みの違い

Vite は public フォルダを静的アセットのルートとして扱います。つまり、ここに置かれたファイルは処理されず、そのまま提供されます。しかし、魔法が起きるのはファイル名を正しくつけたときです。Vite は favicon.ico や favicon.svg といった特定のファイル名を自動検出し、ビルド時に必要な HTML タグを注入します。

このアプローチにより、メインのアイコンに対して複雑なプラグインを使ったり、index.html に手動で <link> タグを追加したりする必要がなくなります。これは時間を節約するクリーンで意見のあるワークフローですが、正確さが求められます。ファイル名のスペルを間違えると、ブラウザはアイコンを見つけられず、あの忌まわしいデフォルトのグレーの四角が表示されてしまいます。

ステップ 1: ソースファイルの準備

コードに触れる前に、適切なアセットを用意しましょう。2026 年の基準では、単一の PNG ファイルだけでは不十分です。スケーラビリティのための SVG と、レガシーブラウザ対応のためのマルチ解像度 ICO が必要です。ロゴしかない場合は、Mzu favicondl を使って必要なサイズを瞬時に生成しましょう。

SVG は最適化されていることを確認してください。隠れたレイヤーや不要なメタデータは削除しましょう。たとえ 16x16 ピクセルのアイコンであっても、肥大化した SVG は初期描画を遅くします。ICO ファイルには、16x16、32x32、48x48 のサイズを単一のコンテナに含めてください。

ステップ 2: ファイルを Public ディレクトリに配置

プロジェクトのルートディレクトリに移動します。public という名前のフォルダが表示されるはずです。これが静的アセットが存在する唯一の場所です。favicon.svg と favicon.ico をこのフォルダに直接ドラッグ＆ドロップしてください。

これらのファイルを src/assets に置いてはいけません。そこに置くと、ビルド処理中に Vite がファイル名にハッシュを付与します（例：favicon.a1b2c3.svg）。これにより自動検出メカニズムが機能しなくなります。ファイル名を正確に保つ必要がある場合は、public フォルダが安全地帯です。

ステップ 3: 設定の確認

npm run dev で開発サーバーを実行します。ブラウザを開いてページのソースを確認してください。以下のような行が表示されているはずです：

<link rel="icon" type="image/svg+xml" href="/favicon.svg" />

これが表示されていれば、Vite はアイコンを正常に検出しています。表示されない場合は、ファイル拡張子を確認してください。Vite は大文字小文字を区別します。Favicon.svg は機能せず、favicon.svg でなければなりません。これは数時間のデバッグ時間を無駄にする一般的な落とし穴です。

ダークモードと Apple Touch Icon への対応

プロフェッショナルな設定は、デフォルトのタブアイコン以上のものです。現代のユーザーは、システム設定に合わせてサイトが適応することを期待しています。ブランドがダーク背景を使用している場合、ダークモードでは白いロゴが見えなくなることがあります。これには専用の SVG バリエーションが必要です。

ダークモード対応の実装

favicon-dark.svg という名前の 2 つ目の SVG ファイルを作成します。index.html（src ではなく public フォルダ内）に、条件付きのリンクタグを追加します。これにより、ブラウザは prefers-color-scheme メディアクエリに基づいてアイコンを切り替えます。

<link rel="icon" type="image/svg+xml" href="/favicon.svg" media="(prefers-color-scheme: light)" /> <link rel="icon" type="image/svg+xml" href="/favicon-dark.svg" media="(prefers-color-scheme: dark)" />

このシンプルな追加により、ユーザーの OS 設定に関係なく、ブランドが鮮明で洗練された状態で表示されます。これは高品質なエンジニアリングをアピールする小さな詳細です。

Apple Touch Icon の設定

iOS のモバイルユーザーには異なるアイコンが必要です。「ホーム画面に追加」された際、ブラウザは 180x180 の PNG を期待します。public フォルダに apple-touch-icon.png という名前のファイルを配置してください。ブラウザがリクエストすると、Vite は自動的にこのファイルを提供します。

マニフェストファイルも忘れずに。public フォルダに manifest.json を作成し、index.html でリンクしてください。このファイルは、Android や iOS にアプリをスタンドアロンの PWA として表示する方法を伝えます。マニフェスト構造の詳細については、Web App Manifest Favicon のガイドをご覧ください。

一般的な落とし穴と解決策

設定が正しくても、問題は起こり得ます。最も頻繁な問題はキャッシュです。ブラウザは favicon のキャッシュに対して非常に積極的です。アイコンを更新しても古いまま表示される場合、バグではなくキャッシュされたバージョンを見ています。

更新を強制するには、index.html のリンクタグにクエリ文字列を追加します。例：href="/favicon.svg?v=2"。これでブラウザに新しいファイルを取得させることができます。あるいは、ブラウザのキャッシュをクリアするか、シークレットウィンドウを使用して変更を確認してください。

もう一つの問題は、コンソールに表示される 404 エラーです。ブラウザコンソールに /favicon.ico の 404 エラーが表示される場合、public フォルダからファイルが欠落していることを意味します。SVG を使用していても、一部のブラウザはレガシーな ICO ファイルをリクエストします。これらのエラーを沈黙させるために、必ずフォールバック用の ICO ファイルを提供してください。

最後に、Vite のビルド出力は dist フォルダに出力されることを忘れないでください。デプロイする際は、サーバーが public ディレクトリからファイルを正しく提供していることを確認してください。Vercel や Netlify などの静的ホストを使用している場合、これは自動的に処理されます。カスタムサーバーを使用している場合は、ルーティング設定を確認してください。

Vite アプリの favicon 設定は複雑である必要はありません。ファイルベースの規約を尊重し、適切な形式を提供することで、すべてのデバイスでプロフェッショナルな外観を保証できます。これは趣味のプロジェクトと、本番環境で使えるアプリケーションの違いです。