小程序/H5不支持pages.json中backgroundImage，必须手写custom导航栏；App端可用titleNView配置backgroundImage，路径须为/static/下相对URL且格式严格。
不能直接在 pages.json 里给导航栏设背景图——小程序平台压根不支持 backgroundImage 字段，App 端虽支持但仅限原生层，H5 完全无效。必须分平台处理：App 走 titleNView 配置，小程序/H5 必须手写自定义导航栏。
App 端用 titleNView + backgroundImage 最省事
只对 iOS/Android 生效，微信、支付宝、H5 不识别该配置。图片必须放在 /static/ 下，路径写相对 URL（如 "static/nav-bg.png"），不能用绝对路径或变量拼接。
-
backgroundImage值只能是合法 URL 或 CSS 渐变字符串（如"linear-gradient(to right, #ff0000, #0000ff)"），中间不能有换行或多余空格，否则解析失败回退为灰底 - 图片尺寸建议宽度 ≥ 2 倍屏幕宽度、高度 ≈ 88px（覆盖状态栏+导航栏），否则拉伸失真或裁切
- 渐变字符串里不要写
rgba(0,0,0,0.5)这类带空格的格式，要写成rgba(0,0,0,0.5)（无空格） - 别把
backgroundImage错写在navigationBarBackgroundColor同级位置——它必须嵌套在app-plus→titleNView下
小程序/H5 必须手写 custom 导航栏
先在 pages.json 对应页面设 "navigationStyle": "custom"，否则 --status-bar-height 变量不可用。手写时别用 top: 0 硬顶，否则 iOS 状态栏文字被盖住；也别依赖 uni.getSystemInfoSync().statusBarHeight 直接算高度，某些 Android 机型返回 0 或错值。
- 导航栏容器高度写成
height: calc(var(--status-bar-height) + 44px)，顶部留白用padding-top: var(--status-bar-height)推下去 - 背景图用
background-image: url(...)+background-size: 100% 100%拉满，再叠一层linear-gradient(rgba(0,0,0,0.2), rgba(0,0,0,0.2))防文字看不清 - 如果想让背景图随滚动渐显，监听
onPageScroll的scrollTop，动态改opacity和叠加渐变层透明度——别只调opacity，iOS 上文字会发虚
常见错误现象和绕过方式
真机跑起来没反应？大概率是平台误判或路径写错。比如在小程序里写了 titleNView.backgroundImage，或者把图片放到了 /assets/ 而非 /static/。
- 报错
backgroundImage is not supported in this platform：说明你正在 H5 或小程序环境试图用原生配置，立刻切到 custom 方案 - 图片显示为灰色块：检查路径是否漏了
static/前缀，或图片文件名大小写是否与实际一致（尤其 iOS 真机区分大小写） - 导航栏在部分 Android 机上“下沉”或“溢出”：不用 JS 动态算高度，一律用
var(--status-bar-height)CSS 变量 +calc() - 滚动时背景图闪动或跳变：避免在
onPageScroll中频繁触发setData，改用requestAnimationFrame节流，或只更新style内联样式
最麻烦的不是怎么画出来，而是各平台对“状态栏高度”“安全区域”“滚动事件精度”的处理不一致。哪怕同一份代码，在微信开发者工具里正常，真机上就偏移几像素——这种细节没法靠一次配置解决，得靠真机反复测。
