全局关闭沉浸式状态栏最直接有效的方式是修改manifest.json设"immersed":false,因其在app-plus→statusbar节点下作为原生层统一策略,优先级高于pages.json单页配置和运行时API,且无需JS逻辑、真机打包后一劳永逸生效。

全局关闭沉浸式状态栏,最直接有效的方式是修改 manifest.json,设 "immersed": false —— 这会覆盖所有页面的默认沉浸行为,且无需写任何 JS 逻辑。
为什么改 manifest.json 才算“全局关闭”
uni-app 的 App 端默认启用沉浸式(immersed: true),这意味着即使你没写任何导航栏配置,页面内容也会顶到状态栏下方。这个开关在 manifest.json 的 app-plus → statusbar 节点下,是原生层的统一策略,优先级高于 pages.json 中单页配置。
-
pages.json里设navigationStyle: "custom"或titleNView: false是“逐页控制”,不是全局;不配就仍走沉浸式默认逻辑 -
plus.navigator.setFullscreen(true)是运行时 API,只对当前页面生效,且必须在onShow中调用,无法做到“一劳永逸” -
immersed: false会让系统 WebView 恢复传统布局模式:状态栏独立存在,页面内容自动下移,不再需要手动计算--status-bar-height或加padding-top
manifest.json 正确写法(必须用代码视图)
打开 manifest.json → 切换到「源码视图」→ 在 "app-plus" 对象内添加或修改 statusbar 配置:
"app-plus": {
"statusbar": {
"immersed": false
}
}
- 不要写成
"immersed": "false"(字符串)或"immersed": 0,必须是布尔值false - 该配置仅对 App 端生效,H5 和小程序不受影响,也无需条件编译
- 改完需重新打包 APK/IPA,HBuilderX 模拟器不识别此配置,真机测试才有效
关闭后还要注意什么
设 immersed: false 后,页面不再顶到状态栏,但可能带来两个隐性问题:
- 状态栏文字颜色可能和页面不协调(比如白底+白字),此时可在
pages.json对应页面加"navigationBarTextStyle": "black"控制前景色 - 若你之前为适配沉浸式写了
padding-top: var(--status-bar-height),现在要删掉,否则会多出一段空白(因为--status-bar-height在非沉浸模式下值为0px) - 部分 Android 机型(如华为 EMUI 12+)会忽略
immersed: false,仍显示轻微沉浸效果——这是系统级限制,无法通过 uni-app 配置绕过,只能接受或改用setFullscreen(false)补救
真正全局、零侵入、一次生效的关闭方式只有这一种。别在每个页面重复配 navigationStyle,也别指望 H5 的样式 hack 能影响 App 原生行为。


















