Flutterアプリのアイコンが透明になる問題の原因と解決法
この記事の対象読者
Flutterで作ったAndroidアプリのアイコンが、ホーム画面で透明・グレー・白背景になってしまい困っている人。
症状
Google Play Storeではアイコンが正常に表示されるのに、ホーム画面のアイコンが透明（またはグレー）になる。
具体的には：
- Play Storeのアプリページ → 紫背景に本のアイコン（正常）
- ホーム画面 → 白い円の中に小さい紫の四角（異常）
キャッシュクリアやアプリの再インストールをしても直らない。
原因
Android 8.0（API 26）以降のadaptive iconの仕組みに問題があった。
adaptive iconの構造
android/app/src/main/res/
├── mipmap-anydpi-v26/
│ ├── ic_launcher.xml ← ここがadaptive iconの定義
│ └── ic_launcher_round.xml
├── mipmap-xxxhdpi/
│ └── ic_launcher.png ← 従来のPNGアイコン（フォールバック用）
└── drawable-xxxhdpi/
└── ic_launcher_foreground.png ← foregroundレイヤー
adaptive icon XMLはforegroundとbackgroundの2レイヤーを合成してアイコンを生成する：
<!-- mipmap-anydpi-v26/ic_launcher.xml -->
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@drawable/ic_launcher_background"/>
<foreground android:drawable="@drawable/ic_launcher_foreground"/>
</adaptive-icon>
根本原因：foregroundファイルの不在
XMLが@drawable/ic_launcher_foregroundを参照しているのに、drawable-*フォルダにic_launcher_foreground.pngが存在しなかった。
Flutterプロジェクトのデフォルト構成では、flutter create時にadaptive icon XMLが生成されるが、foreground画像は自動生成されない。結果として：
- XMLが存在しない画像を参照
- Androidがforegroundのレンダリングに失敗
- アイコンが透明/グレーにフォールバック
Play Storeでは正常に見える理由：Play Storeはアップロード時の512x512アイコン画像を表示しており、端末のadaptive icon仕組みとは無関係。
試したが効果がなかった対処法
| バージョン | 対処 | 結果 |
|---|---|---|
| v1.0.9 |
ic_launcher_round.pngを全密度フォルダに追加 |
変わらず |
| v1.0.10 | background XMLを@color/から@drawable/(gradient shape)に変更 |
変わらず |
| v1.0.11 |
mipmap-anydpi-v26フォルダごと削除（PNGフォールバック） |
アイコンは出るが白背景+小さい四角 |
| v1.0.12 | foreground PNGを1.6倍に拡大＋adaptive icon XML復活 | 本が大きすぎ＋背景グレーに悪化 |
v1.0.11でPNGフォールバックにしたことでアイコン自体は表示されるようになったが、Androidのランチャーが丸いマスクを適用するため、四角いPNGアイコンが白い円の中に小さく表示される見栄えの悪い結果になった。
v1.0.12ではforeground PNGを用意したが、2つの問題があった：
- foreground PNGの背景が不透明なグレーだった → backgroundレイヤーの紫グラデーションが完全に隠れた
- アイコンをキャンバスの100%まで拡大した → 大きすぎて見栄えが悪い
解決法
1. foreground画像を用意する
drawable-*の各密度フォルダにic_launcher_foreground.pngを配置する。
| 密度 | サイズ |
|---|---|
| mdpi | 108x108 |
| hdpi | 162x162 |
| xhdpi | 216x216 |
| xxhdpi | 324x324 |
| xxxhdpi | 432x432 |
foreground画像は以下の要件を満たすこと：
- 背景は完全に透明（alpha=0）にする。不透明な背景があるとbackgroundレイヤー（グラデーション等）が完全に隠れてしまう
- アイコン本体はキャンバスの約48〜50%のサイズで中央に配置する
- adaptive iconのsafe zoneは全体の約61%（内側66dp / 全体108dp）。重要な部分はこの範囲に収める
- 大きすぎると背景が見えなくなり、小さすぎると丸いマスク内で縮小表示される
2. background画像/XMLを用意する
背景色やグラデーションの場合はXMLで定義できる：
<!-- drawable/ic_launcher_background.xml -->
<?xml version="1.0" encoding="utf-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
android:shape="rectangle">
<gradient
android:startColor="#667eea"
android:endColor="#764ba2"
android:angle="315"
android:type="linear"/>
</shape>
3. adaptive icon XMLを配置する
<!-- mipmap-anydpi-v26/ic_launcher.xml -->
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@drawable/ic_launcher_background"/>
<foreground android:drawable="@drawable/ic_launcher_foreground"/>
</adaptive-icon>
ic_launcher_round.xmlも同じ内容で作成する。
最終的なファイル構成
android/app/src/main/res/
├── mipmap-anydpi-v26/
│ ├── ic_launcher.xml ← adaptive icon定義
│ └── ic_launcher_round.xml ← 同上
├── drawable/
│ └── ic_launcher_background.xml ← 紫グラデーション背景
├── drawable-mdpi/
│ └── ic_launcher_foreground.png ← 108x108
├── drawable-hdpi/
│ └── ic_launcher_foreground.png ← 162x162
├── drawable-xhdpi/
│ └── ic_launcher_foreground.png ← 216x216
├── drawable-xxhdpi/
│ └── ic_launcher_foreground.png ← 324x324
├── drawable-xxxhdpi/
│ └── ic_launcher_foreground.png ← 432x432
├── mipmap-mdpi/
│ └── ic_launcher.png ← フォールバック用PNG
│ ...
チェックリスト
adaptive iconのトラブルに遭遇したら、以下を確認する：
-
mipmap-anydpi-v26/ic_launcher.xmlが存在するか - XMLの
@drawable/ic_launcher_foregroundが参照するPNGが全密度のdrawable-*フォルダに存在するか - foreground画像の背景が透明（alpha=0）か（不透明だとbackgroundレイヤーが隠れる）
- foreground画像のアイコンが**キャンバスの約48〜50%**のサイズか（大きすぎても小さすぎてもダメ）
- foreground画像のアイコン部分がキャンバスの中央61%（safe zone: 66dp/108dp）に収まっているか
まとめ
Flutterアプリのアイコンが透明になる原因は、adaptive icon XMLが参照するforeground画像が存在しないことだった。Play Storeでは正常に見えるため発見が遅れやすい。
さらに、foreground画像が存在していても背景が不透明だとbackgroundレイヤーが隠れる、アイコンが大きすぎると背景が見えなくなるといった落とし穴がある。foreground PNGは「透明背景＋キャンバスの約48〜50%サイズ」を守ることが重要。