uni.setnavigationbarcolor在h5端无效，app端需关闭原生导航栏且必须同时传backgroundcolor和frontcolor，微信小程序frontcolor仅支持#000000或#ffffff，uni-app x忽略backgroundcolor；pages.json中statusbar.background生效需"immersed": true且页面内容需适配安全区。
uni.setNavigationBarColor 背景色和页面背景色不一致？先确认平台是否支持
在 H5 端调用 uni.setNavigationBarColor 设置背景色，必然无效——这个 API 根本没在 H5 实现，控制台报 undefined is not a function 是正常现象，不是配置错。APP 端和小程序端才真正走原生逻辑，但行为差异极大：
- APP 端：必须关闭原生导航栏（即
"navigationStyle": "custom"），否则该 API 只影响导航栏区域，不影响状态栏；且backgroundColor必须和frontColor同时传，缺一不可 - 微信小程序：支持，但
frontColor只接受"#000000"或"#ffffff"，其他值会导致整个调用静默失败 -
uni-app x：该 API 的
backgroundColor参数被忽略，状态栏背景恒为透明，只能改文字颜色
pages.json 里 statusbar.background 配了但页面还是白底？检查是否启用沉浸式
APP 端通过 pages.json 配置 statusbar.background 是最稳定的方式，但它有个隐藏前提："immersed": true（默认就是 true）。如果误设为 false，状态栏会“收进”顶部，background 配置直接被忽略。
更常见的问题是：配置生效后，页面内容被顶高了，导致你看到的“页面背景”其实是系统默认白底，而你设的深色只作用于状态栏区域。此时需检查：
- 是否在页面根容器加了
padding-top: var(--status-bar-height, 0)？否则内容会从屏幕顶边开始渲染，遮住状态栏下方区域 - 是否用了自定义导航栏？一旦启用
"navigationStyle": "custom"，statusbar配置就完全失效，状态栏变成透明窗口，颜色得靠 CSS 占位实现 - Android 上是否遗漏了
android:windowLightStatusBar权限？没有它，深色背景配浅色文字可能显示异常
H5 页面顶部出现浅灰/白色条，和页面背景不协调？别碰 theme-color
iOS Safari 对 <meta name="theme-color"> 的解析极其保守：只在硬跳转时读取，SPA 路由切换不触发重载。你用 JS 动态改 content，大概率延迟、卡顿甚至完全不生效。所谓“色差”，其实是地址栏底色（theme-color）和你的页面顶部背景色视觉脱节。
可靠做法是放弃同步控制，改用视觉对齐：
- 在
index.html的中预置一个带id="themeColor"的 meta 标签，颜色选高对比度值（如#1e40af），作为 PWA 冷启动兜底 - 页面顶部加一个固定高度的
<view class="status-bar-placeholder"></view>，背景色与你的页面顶部背景一致 - 该 placeholder 高度不要硬写 20px，优先用
env(safe-area-inset-top)（配合viewport-fit=cover），iOS 下更准确 - 禁用
position: fixed; top: 0的伪导航栏——它不响应安全区，容易错位
自定义导航栏下状态栏颜色“穿帮”？你得自己画出状态栏区域
启用 "navigationStyle": "custom" 后，uni-app 彻底交出状态栏控制权。此时状态栏是透明的，你看到的“颜色”其实是页面内容透上去的。要让它和导航栏颜色一致，必须手动占位：
- 在页面
<template></template>最顶部插入一个<view class="status-bar"></view>，高度设为:style="{ height: statusBarHeight + 'px' }" -
statusBarHeight必须在onLoad或onShow中用uni.getSystemInfoSync().statusBarHeight获取，不能写死（iPhone X 是 44px，安卓多为 24–30px） - 该 view 的背景色必须和你的自定义导航栏背景色完全一致，否则会出现 1px 色差
- CSS 中必须用
position: fixed; top: 0; z-index: 999，否则滚动时会跟着动，或者被其他元素遮挡
最容易被忽略的是：H5 端 uni.getSystemInfoSync().statusBarHeight 返回值不可靠（常为 0 或 20），真机调试时务必用 env(safe-area-inset-top) 替代，否则 iPhone 14 Pro 等机型上会明显错位。
