.NET MAUI でスプラッシュ画面を設定したのに、デバッグ実行ではロゴが表示されるのに Release APK を実機に入れると背景色だけになる――そんな現象は Android 12 以降（Android 14/15含む）で起きがちです。本記事では原因の考え方と、Android ネイティブ側のテーマでロゴと背景を明示して確実に表示させる手順をまとめます。
症状：デバッグは正常、Release APK だけロゴが消える
相談が多いのは、エミュレータ／実機のデバッグではロゴが出るのに、Release APK を作成して実機にインストールすると背景色だけになるパターンです。Resources/Splash/logo.png を MauiSplashScreen に指定していても改善しないことがあります。
| 実行形態 | 端末 | 表示 | よくあるコメント |
|---|---|---|---|
| デバッグ実行 | エミュレータ／実機 | ロゴ表示OK | 「設定は合っているはず」なのに…となりやすい |
| Release APK | 実機（Android 14/15） | 背景色のみ | 紫などの背景だけが出て、中央の画像が欠ける |
なぜ Release だけで起きるのか
結論から言うと、Android 12 以降は起動直後のスプラッシュがAndroid の SplashScreen API（テーマ属性）で決まり、そこに MAUI の生成物や Release 時の最適化（リソースのまとめ方、不要判定など）が絡むことで、ロゴが参照されない状態になりえます。
- MAUI 側のスプラッシュ設定は「生成」までを面倒見ますが、端末が最初に描くのはAndroid のテーマです。
- Release はデバッグと違い、パッケージングや最適化の条件が変わるため、ギリギリの参照だと欠落が表面化します。
- 上書きインストールを繰り返すと、端末側のキャッシュで「直ったはずなのに変わらない」こともあります。
| 設定場所 | 代表 | 役割 |
|---|---|---|
| MAUI（クロスプラットフォーム） | <MauiSplashScreen ... /> | スプラッシュ用 drawable の生成や既定テーマの材料 |
| Android（ネイティブ） | styles.xml のテーマ属性 | OS が起動直後に描画する背景・アイコンの指定（Android 12+） |
| MainActivity | [Activity(Theme=...)] | どのテーマで起動するかを決める（ここがズレると反映されない） |
解決方針：Android 側でスプラッシュを明示して安定させる
最も安定するのは、MAUI の設定だけに頼らず、Android のスプラッシュテーマで背景とロゴを明示する方法です。特に「Release だけ」起きる場合は、OS が参照する属性を確実に指定するのが近道です。
手順：カスタムスプラッシュテーマを作って MainActivity に適用
以下の手順で、Maui.SplashTheme を継承したカスタムテーマを作り、MainActivity に適用します。styles.xml の Build Action を AndroidResource にするのが重要です。
| ファイル | パス | Build Action | 目的 |
|---|---|---|---|
styles.xml | Platforms/Android/Resources/values/ | AndroidResource | スプラッシュ用テーマ（背景・ロゴ）を定義 |
logo.png | Platforms/Android/Resources/drawable/ | AndroidResource | Release でも確実に参照できるロゴを用意 |
styles.xml の例
ポイントは次の3つです。（1）android:windowBackground を @drawable/maui_splash にする、（2）背景色を windowSplashScreenBackground で明示、（3）ロゴを windowSplashScreenAnimatedIcon で明示です。
<?xml version="1.0" encoding="utf-8"?>
<resources>
<style name="CustomSplashTheme" parent="Maui.SplashTheme">
<!-- MAUI のスプラッシュ描画を背景として使う -->
<item name="android:windowBackground">@drawable/maui_splash</item>
<!-- Android 12+：スプラッシュ背景を白に固定したい場合 -->
<item name="android:windowSplashScreenBackground">@android:color/white</item>
<!-- Android 12+：中央に出すロゴ（AndroidResource の drawable） -->
<item name="android:windowSplashScreenAnimatedIcon">@drawable/splash_icon</item>
<!-- 不要なら透明（ロゴの丸背景が出るのを抑える） -->
<item name="android:windowSplashScreenIconBackgroundColor">@android:color/transparent</item>
<!-- スプラッシュ後に本体テーマへ切り替え（必要に応じて） -->
<item name="postSplashScreenTheme">@style/Maui.MainTheme</item>
</style>
</resources>
| 属性 | 意味 | 効かせたいポイント |
|---|---|---|
android:windowBackground | 起動直後の背景 | MAUI が生成した @drawable/maui_splash を確実に使う |
android:windowSplashScreenBackground | Android 12+ の背景色 | 「MAUI の Color が効かない」端末でも背景を固定する |
android:windowSplashScreenAnimatedIcon | Android 12+ の中央アイコン | Release でロゴが欠ける場合でも OS 側へ明示する |
MainActivity.cs でテーマを指定
MainActivity の Theme を @style/CustomSplashTheme に変えます。ここが違うと、styles.xml を直しても反映されません。
using Android.App;
using Android.Content.PM;
using Microsoft.Maui;
namespace YourAppNamespace;
[Activity(
Theme = "@style/CustomSplashTheme",
MainLauncher = true,
ConfigurationChanges =
ConfigChanges.ScreenSize |
ConfigChanges.Orientation |
ConfigChanges.UiMode |
ConfigChanges.ScreenLayout |
ConfigChanges.SmallestScreenSize |
ConfigChanges.Density)]
public class MainActivity : MauiAppCompatActivity
{
}
背景を白にしたい場合の考え方
MauiSplashScreen の Color だけで白を狙うより、Android テーマの android:windowSplashScreenBackground で白を指定した方が再現性が高いです。Android 12+ の初期描画はテーマが優先されるため、まず OS 側の背景を固定し、その上で MAUI 側の色を揃える、という順番が安定します。
参考：MAUI 側の設定例（こちらは「生成物の見え方を揃える」目的）
<ItemGroup>
<MauiSplashScreen Include="Resources\Splash\logo.png"
Color="#FFFFFF"
BaseSize="128,128" />
</ItemGroup>
ロゴを確実に出す：drawable として配置して参照する
Release で MAUI 側の参照が揺れる場合に備え、ロゴを Android の drawable リソースとしても配置します。ファイル名はリソース制約に合わせ、小文字・数字・アンダースコアに寄せるのが無難です。
- 配置：
Platforms/Android/Resources/drawable/logo.png - Build Action：AndroidResource
- テーマから参照：
@drawable/logo（または後述の@drawable/splash_icon） - 避けたい例：
Logo.png、splash-logo.png、logo final.png
ロゴのサイズを調整したい場合（layer-list で幅・高さを固定）
ロゴを直指定するとサイズ感の調整が難しいため、layer-list の XML を挟んでサイズを固定します。これで端末差が出にくくなり、見た目のチューニングもしやすくなります。
例：Platforms/Android/Resources/drawable/splash_icon.xml
<?xml version="1.0" encoding="utf-8"?>
<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
サイズはまず 96〜128dpの範囲で試すのが現実的です。余白が多いロゴは大きめ、余白が少ないロゴは小さめにすると、起動直後の印象が安定します。
インストール前に一度アンインストールする（キャッシュ対策）
地味に効くのが、新しい APK を入れる前に既存アプリを一度アンインストールすることです。上書きインストールを繰り返すと、古いキャッシュ／リソースが残っているような挙動になることがあります。
adb uninstall com.example.yourapp
adb install -r path/to/yourapp-release.apk
再発防止のチェックリスト（Release でのみ起きる場合）
| 確認 | 見る場所 | 落とし穴 |
|---|---|---|
| styles.xml が APK に入っているか | Build Action が AndroidResource | ファイルはあってもビルドに含まれていないことがある |
| MainActivity の Theme が当たっているか | [Activity(Theme=...)] | @style/Maui.SplashTheme のままだとカスタムが効かない |
| ロゴを drawable でも参照しているか | windowSplashScreenAnimatedIcon | MAUI 側だけの参照に依存すると Release で揺れやすい |
| ロゴのファイル名が安全か | logo.png など | 大文字、スペース、ハイフンは避ける |
| ビルドキャッシュを消したか | bin/obj 削除→クリーン→Release 再ビルド | 古い生成物が残ると、修正が反映されないように見える |
補足：iOS のスプラッシュは別物
iOS の起動画面は Storyboard/Asset Catalog などで管理され、Android の styles.xml の考え方をそのまま流用できません。MAUI は共通化できる部分も多いですが、スプラッシュは OS 依存が強い領域なので、Android と iOS は別手順として整理するのが安全です。
まとめ
.NET MAUI のスプラッシュで「Release APK だけロゴが出ない／背景色だけになる」場合は、Android の SplashScreen API に合わせてテーマで明示するのが最も安定します。Maui.SplashTheme を継承したカスタムテーマを作り、windowSplashScreenBackground と windowSplashScreenAnimatedIcon を指定し、必要なら drawable 側にもロゴを置いて layer-list でサイズを調整してください。最後に、端末のキャッシュを疑ってアンインストール→再インストールまで行うと、検証がぶれにくくなります。
コメント