capacitor-splash-screen

Capacitor 中的启动画面

适用场景

以下情况使用：

• 配置或重新生成启动画面／图标资源（npx capacitor-assets generate）
• 启动画面始终不消失、消失过早，或 Web 应用绘制前闪现白屏／黑屏
• Android 12+ 显示纯色背景上的小型裁切图标，而不是完整图像
• 升级到 Capacitor 9 后，Android 的淡出动画消失
• 添加 SceneDelegate.swift 后，iOS 显示黑屏（8.5+）

以下情况不要使用：

• 状态栏／导航栏样式和全面屏边缘间距：safe-area-handling
• 将 AppDelegate 迁移到 SceneDelegate：capacitor-uiscene-migration
• 首次绘制缓慢／包体积问题：capacitor-performance
• 应用商店提交的图标要求：capacitor-app-store

启动机制（判断要编辑什么）

阶段	iOS	Android 12+	Android <= 11
系统启动画面（任何代码运行前）	LaunchScreen.storyboard（UILaunchStoryboardName），图像为 Assets.xcassets/Splash.imageset 中的 Splash	系统 SplashScreen API：主题 AppTheme.NoActionBarLaunch 以 Theme.SplashScreen 为父主题——仅显示图标和背景色	androidx.core:core-splashscreen 兼容库，或 android:background drawable
插件启动画面（直到调用 hide()）	Bridge 视图上的插件覆盖层	通过 API 保持显示的同一个系统启动画面	插件 ImageView／Dialog（androidSplashResourceName、androidScaleType）

大多数 androidScaleType、showSpinner、splashFullScreen、layoutName、useDialog、backgroundColor 选项不适用于 Android 12+ 启动画面（由操作系统绘制）。这些选项仅影响 show() 和 Android 12 之前的设备。

工作流

1. 检查：capacitor.config.* 中的 plugins.SplashScreen、android/app/src/main/res/values/styles.xml、android/variables.gradle（coreSplashScreenVersion）、ios/App/App/Info.plist、ios/App/App/SceneDelegate.swift、assets/ 或 resources/ 文件夹。
2. 安装：npm install @capacitor/splash-screen && npx cap sync。
3. 资源：将源文件放入 assets/（icon-only.png、icon-foreground.png、icon-background.png、splash.png、splash-dark.png；启动画面至少为 2732x2732，图标至少为 1024x1024），然后运行 npm install -D @capacitor/assets && npx capacitor-assets generate（使用 --ios、--android、--pwa 指定范围）。将徽标放在中央约 1/3 区域内，避免被 Android 12+ 的圆形遮罩裁切。
4. 有意控制隐藏时机：设置 launchAutoHide: false，并在首次有意义的绘制后调用 hide()（见下文）。
5. 按需调整 Android 12+：references/android-12-splash.md。
6. 验证（见下文）。

推荐配置

// capacitor.config.ts
plugins: {
  SplashScreen: {
    launchAutoHide: false,     // hide from JS when the UI is ready
    launchFadeOutDuration: 200, // explicit: Capacitor 9 default on Android is 0
    backgroundColor: '#ffffff', // match the first web paint to avoid a flash
  },
},

import { SplashScreen } from '@capacitor/splash-screen';

// after the router's first view has rendered (e.g. in a root component's mounted/useEffect)
await SplashScreen.hide(); // optional: { fadeOutDuration: 300 }

注意事项：

• 设置 launchAutoHide: false 后，如果在调用 hide() 前发生 JS 崩溃，应用会卡在启动画面。请添加备用方案：setTimeout(() => SplashScreen.hide(), 8000)。
• 自动隐藏时的默认值为 500 ms（launchShowDuration）。较长的固定时长会损害用户感知的启动速度；应在就绪时隐藏。
• 将 <body>／根元素背景设为与启动画面相同的颜色，否则原生启动画面与网页首次绘制之间的间隙会闪白（深色模式下会闪黑）。
• 实时更新（capgo-live-updates）：独立于 hide() 调用 notifyAppReady()；不要让其中一个调用依赖另一个。

版本说明

版本	变更
4	Android 使用 Android 12 SplashScreen API 和兼容库
7	移除 SplashScreenShowOptions / SplashScreenHideOptions 类型 -> ShowOptions / HideOptions
8	coreSplashScreenVersion = '1.2.0'
8.5（iOS）	UIScene 模板在 SceneDelegate 中创建窗口和 CAPBridgeViewController；Main.storyboard 不再提供根视图控制器。LaunchScreen.storyboard 未变，仍为必需项。
9	Android 的 launchFadeOutDuration 默认值从 200 变为 0（旧默认值可能会阻止 hide() 后立即进行的 UI 更改）。若要保留淡出效果，请显式设置为 200。

iOS 注意事项（Capacitor 8.5+ 场景）

• 在 Info.plist 中保留 UILaunchStoryboardName = LaunchScreen。Apple 要求使用启动故事板；删除它会导致画面出现黑边或尺寸错误。
• 不要以为在 Main.storyboard 中添加视图或自定义视图控制器就会显示出来：8.5 的 SceneDelegate 会在代码中设置 window.rootViewController = CAPBridgeViewController()。如需自定义，请改用 CAPBridgeViewController 子类。
• 配置场景清单后，启动后立即出现黑屏，说明 SceneDelegate 未创建窗口（缺少 window = UIWindow(windowScene:) + makeKeyAndVisible()），或 UISceneDelegateClassName 指向了不存在的类。使用 capacitor-uiscene-migration 修复。
• iOS 会缓存故事板。修改后，请从设备或模拟器中删除应用并重新安装。
• 在可调整大小的窗口、iPad 或折叠屏设备上，启动故事板必须使用 Auto Layout 约束，而不是固定的 frame（如果存在，请参阅 capacitor-ios-resizability）。

验证

1. 运行 npx cap sync，然后进行原生干净构建（在 Xcode 中选择 Product > Clean Build Folder；在 android/ 中运行 ./gradlew clean）。
2. 删除并重新安装应用（两个平台都会缓存启动屏幕）。
3. 在以下设备上冷启动：iOS 设备（浅色和深色模式）、Android 12+ 设备、Android <= 11 模拟器（如果 minSdk 允许；Capacitor 9 的 minSdk 为 26）。
4. 确认：没有白屏或黑屏闪烁；首屏可见后启动屏幕会隐藏；淡出效果符合配置的时长。
5. 使用 grep 查找残留内容：

grep -rn "launchFadeOutDuration\|launchAutoHide" capacitor.config.*
grep -n "Theme.SplashScreen\|postSplashScreenTheme" android/app/src/main/res/values/styles.xml
/usr/libexec/PlistBuddy -c "Print :UILaunchStoryboardName" ios/App/App/Info.plist

错误处理

症状 / 消息	原因	修复方法
启动屏幕一直显示	launchAutoHide: false，且从未运行 hide()（JS 错误、导入错误，或在插件加载前调用）	检查 Web 控制台；添加超时回退
升级到 Capacitor 9 后淡出效果消失（Android）	launchFadeOutDuration 的默认值现为 0	设置 launchFadeOutDuration: 200
hide() 后立即进行的 UI 更改不可见（Android，低于 9）	200 ms 淡出阻止了更新	设置 launchFadeOutDuration: 0
Android 12+ 显示小图标，图像被裁切	操作系统的启动屏幕按设计仅显示图标	提供适配自适应图标安全区域的图片；调整 windowSplashScreenAnimatedIcon
Android 12/12L 未通过第三方启动器或 Android Studio 显示启动屏幕	平台问题已在 Android 13 中修复	从系统自带的启动器进行测试
error: resource drawable/splash not found	androidSplashResourceName 或样式引用了不存在的 drawable	重新生成资源，或修正配置和 styles.xml 中的名称
AAPT: error: style attribute 'attr/windowSplashScreenAnimatedIcon' not found	缺少 core-splashscreen 依赖项	恢复 implementation "androidx.core:core-splashscreen:$coreSplashScreenVersion"
采用 8.5 场景后 iOS 黑屏	SceneDelegate 中未创建窗口	参阅 iOS 注意事项 / capacitor-uiscene-migration
iOS 仍显示旧启动屏幕	启动屏幕缓存	删除应用；必要时重启设备，然后重新安装

资源

• 插件 API：https://capacitorjs.com/docs/apis/splash-screen
• 启动屏幕和图标指南：https://capacitorjs.com/docs/guides/splash-screens-and-icons
• 更新到 9.0：https://capacitorjs.com/docs/updating/9-0
• Android SplashScreen API：https://developer.android.com/develop/ui/views/launch/splash-screen