启动页和图标由manifest.json配置+static/下静态资源+云打包三者共同决定;splashscreen和icons须置于app-plus节点,鸿蒙复用android字段,iOS必须用Storyboard ZIP包,路径须为static/相对路径且无透明通道。
启动页和图标不是靠写 vue 页面控制的,改 manifest.json + 放对文件 + 走云打包,三者缺一不可;90% 的“不生效”问题都卡在这三步上。
manifest.json 里 splashscreen 和 icons 必须放在 app-plus 下
这两个配置项不能写在根节点、h5 或 mp-weixin 下,也不能拼错字段名(比如写成 splashScreen 或 icon)。鸿蒙和 Android 共用 android 子字段,iOS 则必须走 Storyboard,splashscreen.ios.image 在真机上会被静默忽略。
-
splashscreen至少要包含autoclose: true、waiting: true,否则启动页可能一闪就关或卡住不关 -
icons下的android支持mdpi/hdpi/xhdpi/xxhdpi/xxxhdpi,鸿蒙只读xxxhdpi(推荐 192×192) - iOS 图标必须配全:
appstore(1024×1024)、iphone.2x(120×120)、iphone.3x(180×180),漏一个真机就 fallback 到默认图标
static/ 目录下文件路径和命名必须完全一致
所有路径都得是 static/xxx.png 这种格式,不能带开头斜杠(/static/)、不能用 assets/ 或 src/,也不能用网络地址。大小写、扩展名、@2x 后缀,错一个就加载失败。
- Android 启动图建议提供三档:
static/splash/splash-hdpi.png(480×800)、static/splash/splash-xhdpi.png(720×1280)、static/splash/splash-xxhdpi.png(1080×1920) - iOS Storyboard 打包需 ZIP 包,解压后根目录直接是
LaunchScreen.storyboard、launchimage@2x.png、launchimage@3x.png,不能有子文件夹 - 所有 PNG 图标必须无透明通道(Alpha 通道),否则某些安卓机型边缘发灰,iOS 审核也可能被拒
云打包是唯一生效途径
本地运行、HBuilderX 真机调试、甚至离线打包(未勾选鸿蒙/IOS)都不会读取这些配置。只有「发行 → 原生 App-云打包」并勾选对应平台,才会把 manifest.json 配置编译进原生包。
- 鸿蒙打包时,系统自动从
app-plus.icons.android.xxxhdpi取图,不用额外建harmonyos字段 - iOS 打包若没传 Storyboard ZIP,HBuilderX 会 fallback 到纯白屏,这不是 bug,是系统强制策略
- Android 上设
alwaysShowBeforeRender: true能防首页 JS 没加载完就关启动页导致的闪白
最容易被忽略的是:iOS Storyboard 的图片引用必须用 Aspect Fill 或 Center 拉伸模式,且文字/Logo 必须提前画进 PNG 里——Storyboard 本身不支持动态文本渲染;另外,启动页图片背景色最好和首页 pages.json 里的 globalStyle.background 保持一致,否则视觉上会“断层”。











