小程序主题切换不能直接改CSS文件，因构建时已编译样式，运行时无法插入新规则；仅支持CSS变量或class切换，推荐用:root配合document.documentElement.style.setProperty批量更新，并需调用原生API同步导航栏、TabBar等。
小程序端主题切换为什么不能直接改 CSS 文件
因为小程序的样式系统在构建时就完成了编译和注入，@import、document.write、动态创建 <style> 标签等 Web 常用手段在微信/支付宝/百度等小程序环境中全部无效。运行时无法插入新样式规则，document.styleSheets 是只读的，调用 insertRule 会直接报错 Failed to execute 'insertRule' on 'CSSStyleSheet'。
真正能生效的只有两类方式：CSS 变量（var(--xxx)）或 class 切换（如 .theme-dark .btn）。前者更轻量、热更新友好；后者需预编译多套样式，但兼容性更“硬核”——尤其对某些不支持 CSS 变量的老版微信小程序（6.8.x 以下）。
必须用 :root + document.documentElement.style.setProperty 吗
不是必须，但这是目前最稳的路径。小程序环境（尤其是微信）支持 :root 伪类，且 document.documentElement.style.setProperty 能实时触发样式重计算，无需强制重排或 hack。
注意三点：
- 不要在组件
data或computed中直接返回颜色值再绑定:style，这会导致原生组件（如<uni-button>）不响应、部分平台（如 QQ 小程序）样式丢失 - 不要用
uni.setStorageSync存完就完事——必须在App.vue的onLaunch和每个页面的onShow中主动读取并应用，否则冷启动或后台切回时主题会回退 - 避免在
mounted中一次性 set 大量变量，建议封装成批量更新函数，用Object.entries(themeConfig[theme]).forEach(([k, v]) => document.documentElement.style.setProperty(k, v))
如何让导航栏、TabBar、自定义组件同步变色
纯 CSS 变量只能控制 Web 渲染层，小程序原生容器（导航栏、TabBar、下拉刷新背景）必须调用对应 API 主动设置。
实操要点：
- 导航栏：切换主题后立即调用
uni.setNavigationBarColor({ backgroundColor: themeVars['--nav-bg'], frontColor: themeVars['--nav-text'] }) - TabBar：用
uni.setTabBarStyle设置backgroundColor和color，图标需配合uni.setTabBarItem单独更新iconPath和selectedIconPath（图标资源必须按主题命名，如tab-home-light.png/tab-home-dark.png） - 自定义组件内颜色：不要写
:style="{ color: $store.state.theme.primary }"，统一用class="text-primary"配合 CSS 变量定义：.text-primary { color: var(--primary-color); }
为什么 uni.onThemeChange 在小程序里经常不触发
uni.onThemeChange 只监听系统级深色模式切换（如用户在手机设置里开关深色），不响应你代码里手动调用的 changeTheme('dark')。它本质是个被动监听器，不是主题变更广播。
所以别依赖它驱动 UI 更新。正确做法是：
- 封装一个
setTheme(themeName)函数，内部完成三件事：写入 storage、更新全局状态（如uni.$u.theme）、调用原生 API 设置导航栏/TabBar、批量更新:root变量 - 所有需要响应主题的页面，在
onShow中读取当前主题并 apply，而不是靠事件监听——小程序生命周期中事件总线可靠性低，且容易漏绑 - 如果真要用事件，用
uni.$emit+uni.$on，但务必在onUnload里uni.$off，否则页面销毁后监听器还在，造成内存泄漏和重复执行
最易被忽略的是：小程序没有全局 CSS 作用域隔离，:root 变量一旦设错（比如拼错变量名、值为空字符串），整个主题就会失效且无报错提示——建议在主题配置对象里加 validate() 检查必填项，上线前用 console.log(getComputedStyle(document.documentElement).getPropertyValue('--primary-color')) 手动验值。
