uni-app 的启动图和图标需通过 manifest.json 配置与 static/ 下静态资源配合实现,仅云打包或离线打包生效;Android 启动图需各密度图全提供,iOS 必须用 LaunchScreen.storyboard zip 包,图标路径必须为 static/ 开头且无透明通道。

App 启动图(Splash Screen)和图标在 uni-app 中不是写代码实现的,而是通过 manifest.json 配置 + 静态资源文件组合生效的。改完不打包就看不到效果,这是最常被卡住的点。
manifest.json 里怎么配启动页(splashscreen)
启动页配置必须放在 app-plus 节点下,不能写在 h5 或 mp-weixin 里。鸿蒙和 Android 共用同一套 splashscreen 配置,iOS 则走 Storyboard 方式(后面单独说)。
-
autoclose设为true才会自动关闭;设false就得手动调用plus.navigator.closeSplashscreen() -
delay单位是毫秒,但实际关闭时机还受首页渲染速度影响,设成0更稳妥 -
android下各密度图必须提供,否则低分辨率设备可能拉伸或黑屏:hdpi(480×800)、xhdpi(720×1280)、xxhdpi(1080×1920) - 图片路径必须是
static/下的相对路径,如"static/splash/splash-xhdpi.png",不能用assets/或src/ - 可加
background字段统一背景色,比如"#FFFFFF",避免图片未加载时闪白
iOS 启动页为什么不能只配图片
iOS 不支持纯图片启动页配置,manifest.json 里的 splashscreen 对 iOS 无效。它强制使用 Storyboard —— 一个 XML 描述的静态界面,由 Xcode 渲染,启动极快。
- HBuilderX 要求你提供一个 zip 包,里面**只能有且仅有**一个
LaunchScreen.storyboard文件和它引用的.png图片 - 不能有子目录,zip 解压后应直接看到
LaunchScreen.storyboard和bg.png这类文件 - Storyboard 中图片需设为
Aspect Fill或Center模式,否则在 iPhone Plus 或 iPad 上容易裁切 - 文字、Logo 等元素必须嵌入图片中,Storyboard 本身不支持动态文本渲染
- 如果没提供 zip,HBuilderX 会 fallback 到纯白屏,不是 bug,是 iOS 系统限制
图标配置的平台差异和路径陷阱
图标路径写错、尺寸漏配、格式不兼容,是打包后图标不显示的三大主因。Android 和 iOS 的配置结构不同,不能混用。
- Android 图标走
icons.android,键名是密度标识(hdpi、xxhdpi),不是尺寸数字 - iOS 图标走
icons.ios,键名是尺寸字符串("60x60"、"180x180"),值是对应 PNG 路径 - 所有图标必须是无透明通道的 PNG(iOS 官方要求),Alpha 通道会导致审核被拒
- iOS 要求 1024×1024 大图上传 App Store Connect,但
manifest.json里不用配它,那是云端打包后单独上传的 - 路径别写成
/static/icon.png(带开头斜杠),uni-app 会识别失败,正确是"static/icon.png"
改完配置后为什么还是旧图标或白屏
因为这些配置只在「云打包」或「本地离线打包」时才注入原生工程。开发时预览(运行到浏览器 / 模拟器)完全不读取 manifest.json 里的图标和启动页。
- HBuilderX 中必须点「发行 → 原生 App-云打包」,勾选目标平台(iOS / Android / 鸿蒙),才能生成含新配置的安装包
- CLI 项目要执行
npm run build:app-plus(Android)或npm run build:ios,再用 Xcode 打开生成的项目编译 - 鸿蒙平台目前只支持云打包,本地离线打包暂未开放
- 图标文件若放在
src/assets下,云打包时不会被识别——必须放static/目录 - 修改
manifest.json后,HBuilderX 右上角会有「配置已更改,请重新打包」提示,忽略它等于白改
真正容易被忽略的是:iOS Storyboard zip 包的结构约束、Android 启动图各密度图的命名一致性、以及所有路径都必须基于 static/ 目录——这三个点错一个,打包出来的 App 就会回到白屏或默认图标状态。


















