PhoneGap Build构建Ionic应用：Android Splash Screen白屏问题求助

我之前帮好几个开发者搞定过类似的问题——Android端的启动图在PhoneGap Build上经常因为细节配置或者资源问题掉链子，咱们一步步来排查解决：

1. 先把config.xml的Android启动图配置盯紧 #

首先确认你有没有针对Android平台完整配置splash节点，每个dpi的横竖屏图片都不能少，路径也不能写错（PhoneGap Build对路径大小写、层级要求很严）。给你个标准配置参考：

<platform name="android">
    <!-- 横屏启动图 -->
    <splash src="res/screen/android/splash-land-hdpi.png" density="land-hdpi" />
    <splash src="res/screen/android/splash-land-ldpi.png" density="land-ldpi" />
    <splash src="res/screen/android/splash-land-mdpi.png" density="land-mdpi" />
    <splash src="res/screen/android/splash-land-xhdpi.png" density="land-xhdpi" />
    <splash src="res/screen/android/splash-land-xxhdpi.png" density="land-xxhdpi" />
    <splash src="res/screen/android/splash-land-xxxhdpi.png" density="land-xxxhdpi" />
    <!-- 竖屏启动图 -->
    <splash src="res/screen/android/splash-port-hdpi.png" density="port-hdpi" />
    <splash src="res/screen/android/splash-port-ldpi.png" density="port-ldpi" />
    <splash src="res/screen/android/splash-port-mdpi.png" density="port-mdpi" />
    <splash src="res/screen/android/splash-port-xhdpi.png" density="port-xhdpi" />
    <splash src="res/screen/android/splash-port-xxhdpi.png" density="port-xxhdpi" />
    <splash src="res/screen/android/splash-port-xxxhdpi.png" density="port-xxxhdpi" />
</platform>

2. 图片尺寸和格式必须踩准Android的要求 #

Android对启动图的尺寸有严格对应，错一个都可能显示异常：

• ldpi：竖屏200x320 / 横屏320x200
• mdpi：竖屏320x480 / 横屏480x320
• hdpi：竖屏480x800 / 横屏800x480
• xhdpi：竖屏720x1280 / 横屏1280x720
• xxhdpi：竖屏1080x1920 / 横屏1920x1080
• xxxhdpi：竖屏1440x2560 / 2560x1440
  另外必须用PNG格式，别用JPG，也别加透明区域——Android系统会把透明部分直接显示成白屏。

3. 检查Splash Screen插件的配置和版本 #

先确保你在config.xml里正确声明了插件，版本要适配PhoneGap Build的环境：

<plugin name="cordova-plugin-splashscreen" spec="^6.0.0" />

再加上这些关键全局配置，避免白屏或者显示异常：

<preference name="SplashScreenDelay" value="3000" /> <!-- 启动图显示时长，单位毫秒 -->
<preference name="AutoHideSplashScreen" value="true" />
<preference name="SplashShowOnlyFirstTime" value="true" />
<!-- Android专属配置：保持启动图比例，避免拉伸变形 -->
<preference name="SplashMaintainAspectRatio" value="true" />
<!-- 如果你的启动图有透明区域，这里设成和图一致的背景色，防止白漏出来 -->
<preference name="SplashScreenBackgroundColor" value="#000000" />

4. 排查Ionic自身的启动页冲突 #

Ionic默认有自己的启动页控制逻辑，别让它和PhoneGap的插件打架。打开src/app/app.component.ts检查initializeApp方法：

import { SplashScreen } from '@ionic-native/splash-screen/ngx';

// ...

initializeApp() {
  this.platform.ready().then(() => {
    // 要么交给PhoneGap插件自动处理，要么手动控制时确保逻辑一致
    this.splashScreen.show();
    setTimeout(() => {
      this.splashScreen.hide();
    }, 3000);
  });
}

如果同时用了Ionic的SplashScreen插件和PhoneGap的cordova-plugin-splashscreen，建议统一用后者，避免配置冲突。

5. 强制清理PhoneGap Build的缓存 #

有时候PhoneGap Build会缓存旧资源，导致新启动图不生效。最简单的办法：把config.xml里的版本号改一下（比如从1.0.0改成1.0.1），然后点击项目页面的「Rebuild」按钮，强制重新打包所有资源。

6. 用真机测试，别依赖模拟器 #

Android模拟器的dpi适配经常出问题，有时候模拟器显示白屏，但真机上是正常的。务必拿真实的Android设备测试，才能得到准确结果。

内容的提问来源于stack exchange，提问作者user-stacker