Ionic Capacitor iOS端splash screen黑屏无法正常显示如何解决

1. 校验项目全局配置 #

• 确认@capacitor/splash-screen插件已安装，且插件版本与Capacitor核心版本兼容，避免跨版本不兼容导致的渲染失败。
• 检查根目录下的capacitor.config.ts（或capacitor.config.json）文件，确保Splash Screen插件未被禁用，基础配置正确：

// 示例配置（根据你的业务需求调整参数）
plugins: {
  SplashScreen: {
    launchShowDuration: 2000,
    launchAutoHide: true,
    backgroundColor: "#ffffff", // 与启动图背景色保持一致
    showSpinner: false
  }
}

• 配置修改完成后，在项目根目录执行npx cap sync ios，将最新配置同步到iOS原生项目。

2. 校验Xcode原生项目配置 #

• 用Xcode打开ios/App/App.xcworkspace文件，进入项目Target的General页，找到App Icons and Launch Images模块：
  • 确认Launch Screen File选项值为LaunchScreen（Capacitor默认生成的启动屏故事板文件），不可留空或选择Main。
• 进入Target的Info页，检查Info.plist中UILaunchStoryboardName键的值为LaunchScreen，不存在则手动添加。
• 打开Assets.xcassets中的splash图片集，确认所有分辨率的占位图都已填入正确的启动图，图片格式为PNG且无透明alpha通道（iOS部分版本对带透明通道的启动图会出现渲染异常）。
• 打开LaunchScreen.storyboard文件，确认其中的ImageView控件已绑定splash资源，且约束设置为上下左右铺满全屏，无多余边距。

3. 清理缓存重新构建 #

• 在Xcode中按快捷键Command + Shift + K清理构建缓存，再按Command + Shift + Option + K清理派生数据缓存。
• 卸载测试设备/模拟器上已安装的旧版应用，重新运行项目即可正常展示启动屏。

内容的提问来源于stack exchange，提问作者김세림