鸿蒙 APP 启动页白屏治理实录:AI 的两个方案都不满意?把 startIcon 与启动遮罩做成同一张图,完美实现零白屏

6 阅读9分钟

背景:鸿蒙端冷启动的白屏空档

我们是一个 uni-app(Vue3)项目,通过 DCloud 官方链路打包鸿蒙 APP:编译产物落到鸿蒙工程 www 目录,入口 EntryAbility 继承 uni-app 的 UniEntryAbility。

鸿蒙 APP 冷启动的呈现链路是这样的:

进程启动 → 系统门帘(startIcon)→ 主窗口首帧(webview)→ uni-app 页面渲染

系统门帘是鸿蒙给每个 APP 的“启动页”:显示一张 startIcon 图标。而我们的产品诉求是一张浅青→白的垂直渐变设计稿整图(品牌插画元素居中约占四分之三屏高,上下自适应留白),不允许拉伸变形。

问题在于:门帘消失的时机是主窗口首帧就绪,而 uni-app 的页面跑在 webview 里,webview 初始化、JS bundle 加载、页面渲染都要时间。于是冷启动时用户会看到:

  1. 门帘(设计稿整图)消失;
  2. 白屏——webview 还没画出来任何东西;
  3. 页面(或登录页)突然蹦出来。

在安卓端我们用原生启动图 + 应用内遮罩压住了这段空档,鸿蒙端不能比安卓差。这篇文章就是这个问题的完整治理实录。

AI 推荐的两个方案,以及它们为什么满足不了需求

把这个需求丢给 AI,它给出了两个"标准答案":

方案 A:系统级启动窗口

在 module.json5 里给 startWindow 配 start_window_background 颜色 + startIcon 图标,系统会在窗口首帧前渲染它。

局限很硬:鸿蒙的启动窗口只支持纯色背景 + 图标居中缩放。纯色可以是设计稿的顶色,但渐变整图、居中排版、上下自适应留白,全都做不了。它本质上是个“图标 + 底色”,连设计稿的形都撑不起来。

方案 B:uni-app 内置启动图 / 应用内第一屏遮罩

在 pages.json 里配 splashscreen,或者在首页第一屏画一张启动图盖住加载过程。

局限同样硬:这套方案本质仍是 webview 内容。webview 初始化完成之前它根本不存在——恰恰是那段最刺眼的白屏,它一帧都盖不住。自适应排版倒是可以做,但"盖不住空档"这一条就一票否决。

到这里 AI 的弹药打完了:它给的都是合理但常规的方案。但我心里清楚,两个方案的约束(纯色限制、webview 首帧时机)决定了在它们的框架里这个问题无解。

转折点:不问“用什么盖住白屏”,问“能不能让两边一样”

卡住之后我换了个问法。

回看链路:系统门帘显示的 startIcon,恰好就是我们的设计稿整图(鸿蒙启动图标支持整图等比铺满)。门帘消失后接的是我们自己的遮罩/页面——这是两个界面,而两个界面之间的"差异",就是闪动本身。

那为什么不反过来:不是想办法让遮罩去适配门帘,而是让遮罩和门帘直接是同一张图——逐像素一致,交接时理论上就不存在任何变化。

顺着这个思路,方案自然成型:

  1. 用原生 ArkUI 子窗口做启动遮罩(createSubWindow + loadContent),完全自定义排版,不受 webview 首帧时机约束——门帘一撤,遮罩已经在上面了;
  2. 遮罩页直接渲染与门帘同一个资源 startIcon,同样的等比铺满排版。

这是整件事里 AI 没想到、也想不到的一步——它不知道我们看了多少遍 GIF 逐帧对比,不知道"微调对齐的跳动"在用户眼里有多明显。人工介入的价值,从这个转折点开始。

最终方案实现

双窗口架构与信号链路

onWindowStageCreate
  ├─ openSplashWindow(提前到 super 之前发起,fire-and-forget)
  │    ├─ createSubWindow('splash_mask_window') + resize(物理屏宽高) + moveWindowTo(0,0)
  │    ├─ loadContent(SplashWindowPage)
  │    ├─ setWindowBackgroundColor(启动页顶色兜底)
  │    └─ showWindow
  └─ super.onWindowStageCreate(uni-app runtime 启动)

JS 侧就绪 → uni.closeSplashMask() → AppStorage('splashMaskClose')
           → SplashWindowPage @Watch → 160ms 淡出 → destroyWindow

JS 调原生的桥,在 onCreate 里用 Reflect.set 注入 uni 命名空间:

Reflect.set(uni, 'closeSplashMask', (): void => {
  AppStorage.setOrCreate('splashMaskClose', 1);
});

五轮根因排查:每一轮都是“真机现象 → hilog 取证 → 根因 → 修复”

方案落地远不是一帆风顺。我们没有靠猜,每一轮都让 AI 写取证脚本:hilog 设备端 grep 落盘(主机端缓冲区会被别的 APP 日志刷屏轮转,必须在设备端过滤后 recv 回来),配合 hdc snapshot_display 带时间戳连拍 + 顶部白屏占比分析。五轮下来:

第一轮:遮罩四周黑边。 入场转场动画期间,主窗口的 windowRect 是动画中间态的小矩形,拿它去 resize 导致子窗口开小了。修复:resize 直接用 display.getDefaultDisplaySync() 的物理屏宽高 + moveWindowTo(0, 0)。

第二轮:门帘与遮罩交接的 35ms 白闪(最典型)。 hilog 时间线抓到:NotifyCompleteFirstFrameDrawing(门帘移除)比 subWindowBufferAvailable(遮罩首帧)早约 35ms——门帘撤了、遮罩还没画出来,露出的正是遮罩子窗口的白底。而白底的来源更隐蔽:setWindowBackgroundColor 在 loadContent 之前调用会报 1300002(uiContent is null)静默失败,底色一直是默认白。修复两条:

await sub.loadContent(SPLASH_PAGE_PATH);
// 底色必须在 loadContent 之后、showWindow 之前设置(uiContent 才存在)
await sub.setWindowBackgroundColor(splashTopColor); // 启动页顶色,与门帘底色一致
await sub.showWindow();

同时给主窗口底色做轮询重试兜底(入场动画期设置必失败,5ms × 40 次重试直到成功)——这样即使遮罩首帧再慢,露出的也是启动页顶色而不是白色。竞态窗口从 35ms 压到 2~6ms(小于一帧 16.7ms)。

第三轮:"微调对齐"跳动 + 首次冷启闪白。 遮罩页最初是"渐变层 + 内容图"两层排版,和门帘是两套独立绘制,交接时内容位置差几个像素,就是用户说的"启动页面与 startIcon 微调对齐"。更隐蔽的是:第一次冷启图片解码没有缓存,遮罩的 Image 异步解码导致"门帘有内容 → 遮罩先纯渐变(下半近白)→ 内容才出现"的闪白。修复——回到转折点的思路:

Image($r('app.media.startIcon'))
  .width('100%').height('100%')
  .objectFit(ImageFit.Cover)
  .syncLoad(true)   // 同步解码:首帧 buffer 就绪时图已就绪

与门帘同资源、同排版、同步解码——逐像素一致,交接时不再有任何变化。

第四轮:撤遮罩露白。 撤遮罩信号原本挂在首页数据请求完成,但未登录冷启的最终页是登录页,登录页上屏更晚,淡出就把白暴露了。修复:双信号竞速取先到——登录页 onReady + 50ms 一个信号、首页数据就绪 + 250ms 一个信号,谁先到谁撤,重复调用幂等(遮罩页 closing 标志防重)。每条启动路径都等自己的最终页上屏后才淡出,白屏从机制上消除,未登录路径还顺带不用等首页的网络请求。

第五轮:时长压缩。 撤除延时试过 100ms——白屏明显(登录页没上屏);定稿 250ms 延时 + 160ms 淡出(EaseIn 前段透明度变化缓,给底部页面上屏留窗口)。另外留了 4s 兜底定时器:极端情况下 JS 信号丢失也绝不把用户困在启动页上。

uni-app 侧:条件编译隔离

按跨端项目的规矩,所有改动用 #ifdef APP-HARMONY 隔离在鸿蒙端,不碰其他端的渲染路径。

复盘:AI 推荐的方案 ≠ 最优方案

回头看,AI 的两个方案都是"对的"——系统启动窗口就是官方推荐做法,uni-app 内置启动图就是文档里的配置。但它们解决不了这个产品的诉求。这轮协作让我确认了几件事:

1. 人工的核心价值不是写代码,是定义"什么是好的"。 AI 不知道设计稿的渐变留白多重要、不知道逐帧 GIF 里的跳动在用户眼里多刺眼。方案 A/B 在"技术上正确",但产品上不及格——这个判断只能人来做。

2. 换个问法,往往比换个方案更有用。 AI 在"用什么盖住白屏"这个框架里打转,框架内已无解;把问题改写成"能不能让两个界面趋同",答案立刻出现。这种思维模式的灵活性,是目前的人机协作里最值得人工投入的地方。

3. AI 看不见屏幕,所以要替它把"现象"翻译成"证据"。 五轮排查里每一轮的分工都一样:人负责真机观察和录 GIF 描述现象,AI 负责写插桩、取证脚本(hilog 设备端落盘、连拍 + 白屏占比分析),用时间戳把玄学变成 35ms、1300002 这样的确定数字,再针对数字修复。人机各干各擅长的事,五轮循环没有一轮是任何一方独立完成的。

效果

  • 白屏:连拍 30 帧带白屏占比分析,交接期白帧占比 0%;
  • 闪动:遮罩与门帘逐像素一致,状态栏字体色切换瞬间的"微调对齐"消失;
  • 时长:撤除链路压缩 + 未登录路径不再等首页数据请求,整体比优化前缩短约 500ms;
  • 横向对比:比安卓端还要丝滑,启动速度快一点点——鸿蒙端最终用的是 ArkUI 实时渲染的遮罩,与门帘逐像素衔接,反而比安卓的静态启动图过渡更顺。

一句话总结:AI 给的是大概率正确的方案,人给的是"这个问题真正的形状"。当 AI 的两个方案都不满意时,别急着二选一,换个问法,或者——让两个界面干脆成为同一张图。

开源仓库

方案已整理成开源仓库,MIT 协议,uni-app 鸿蒙工程与纯鸿蒙原生工程都适用:

harmony-splash-mask

  • arkts/:遮罩页 + EntryAbility 接入模板(拷贝即用)
  • uni-app/:双信号竞速片段 + 调参经验
  • scripts/:渐变启动图烘焙脚本(参数化,含透明底校验)
  • README.md:五步接入指引 + 五轮根因表

如果你也在治理鸿蒙冷启动白屏,希望它能帮你少踩几个坑;觉得有用的话欢迎点个 Star,有问题欢迎开 Issue。