三者缺一不可：存主题值、动态挂载data-theme、theme.json控制原生样式；否则页面跳转/启动时闪白或闪黑；manifest.json需设darkmode:true和themeLocation，theme.json须放根目录且结构严格为{"light":{},"dark":{}}。
直接存主题值、动态挂载 data-theme、配合 theme.json 控制原生层样式，三者缺一不可。只做 CSS 变量切换或只改 class，都会在页面跳转/启动时闪白或闪黑。
manifest.json 和 theme.json 必须配齐
uni-app 的原生容器（App、小程序、H5）对深色模式的支持依赖 manifest 配置和 theme.json 文件联动。没配 themeLocation，pages.json 里写的 @navBgColor 就是无效变量；没开 darkmode: true，系统就不会触发主题监听逻辑。
-
manifest.json中各平台都要显式开启："darkmode": true，并指定"themeLocation": "theme.json" -
theme.json必须放在项目根目录，结构严格为{"light": {...}, "dark": {...}}，键名不能写错 - 变量名只在
pages.json中生效，比如"navigationBarBackgroundColor": "@navBgColor"，不能用于组件内样式 - 如果想让 App 启动时就按系统偏好加载（而非默认 light），需额外加
"defaultAppTheme": "auto"（部分平台支持）
App.vue 里必须用 uni.setStorageSync + onLaunch/onShow 同步主题状态
用户手动切换主题后，如果不立刻持久化，冷启动时会回到默认主题；如果只在内存里存 isDarkMode，页面跳转或切后台再回来就丢失了状态。
- 切换时立刻执行：
uni.setStorageSync('theme', 'dark')或'light' -
onLaunch中读取：const saved = uni.getStorageSync('theme')，优先用它， fallback 到uni.getSystemInfo的res.theme -
onShow中再读一次，防止从后台恢复时系统主题已变但页面没响应 - 设置
document.documentElement.setAttribute('data-theme', value)，不要用className，否则 CSS 变量作用域会出问题
CSS 变量定义要分层，避免被覆盖
仅靠 [data-theme="dark"] 覆盖全局变量不够稳，尤其在 nvue 或自定义组件中容易失效。必须把变量定义在 :root 和属性选择器里都写全。
- 在
uni.scss里统一定义：
:root {
--bg-color: #ffffff;
--text-color: #333333;
}
[data-theme="dark"] {
--bg-color: #000000;
--text-color: #ffffff;
}
var(--bg-color)，不能硬编码 #fff 或 white
prefers-color-scheme，只能靠 JS 主动设置，且 style 属性不能用 CSS 变量，得用 binding 动态传值监听系统主题变化要区分平台
prefers-color-scheme 在 H5 和小程序里可用，但 App 平台（iOS/Android）要用 plus.navigator.subscribe('uistylechange')，两者不能混用，否则监听失效或重复触发。
- H5 / 微信小程序：用
uni.matchMedia('(prefers-color-scheme: dark)')，onChange回调里更新data-theme - App 平台：只在
#ifdef APP-PLUS块里用plus.navigator.subscribe，并在onUnload或onHide中取消订阅（防内存泄漏） - 监听时机要早于页面渲染，所以必须写在
App.vue的onLaunch，不能等到某个页面的mounted - 用户手动切换后，应禁用系统监听（比如加个开关 flag），避免用户选了“深色”结果系统切回浅色又自动覆盖
最易被忽略的是 theme.json 和 pages.json 的联动时机——它只在页面创建瞬间生效，后续 JS 修改无效。所以导航栏、tabBar 等原生容器的颜色，必须靠这套机制；而页面内容层的颜色，则靠 CSS 变量 + data-theme 控制。两套逻辑不打通，就会出现导航栏是深色、内容却是浅色的割裂现象。
