产品提需求：应用里加“跟随系统 / 浅色 / 深色”三档开关。你调了 setColorMode，应用内三档切换完美。然后去系统设置里切了一下深色模式，App 纹丝不动。更奇怪的是，即使用户切回“跟随系统”，系统再切深色浅色，onConfigurationUpdate 也再也不触发了。

根因不是监听写错了，是 setColorMode 的语义不是“建议”，是覆盖。

HarmonyOS 的颜色模式生效链条是：系统颜色模式传递到 Application 层，Application 层的 setColorMode 值覆盖 UIAbility 实际生效的颜色模式。你一旦调了 COLOR_MODE_DARK，Application 层就被钉死在深色，系统再怎么切，传到这一层就被拦截了。系统视角里这个 App 的有效配置没有变化，自然不会触发 onConfigurationUpdate。onConfigurationUpdate 能收到颜色模式变化的前提是 App 当前处于“跟随系统”状态，也就是 COLOR_MODE_NOT_SET。

手动切换和跟随系统要分开处理

三档开关的正确实现不是三个按钮各调一次 setColorMode 就完事。手动选择“浅色”或“深色”时，直接 setColorMode 生效，同时应用内需要主动通知 UI 层刷新；用户选择“跟随系统”时，调 COLOR_MODE_NOT_SET，把监听链路重新接回来，此后 onConfigurationUpdate 才会因为系统切换而触发。

typescript

import { ConfigurationConstant } from '@kit.AbilityKit'

// 跟随系统
context.getApplicationContext()
  .setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET)

// 手动锁定深色
context.getApplicationContext()
  .setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK)

颜色值不要在 aboutToAppear 里缓存

另一个常见的“切了不生效”根因在组件层。aboutToAppear 里把颜色取出来存进 @State 变量，之后一直用那个变量，系统切换颜色模式时变量不会自己变。$r('app.color.bg') 应该在 build 中实时解析，或者至少在每次需要时重新取值，不要提前固化成一个普通字符串。

typescript

Column() {
  Text('内容')
}
.backgroundColor($r('app.color.bg'))

资源限定符目录本身是可靠的：resources/dark/element/color.json 和 resources/base/element/color.json 同名对应，系统按当前 colorMode 自动选择。出问题的地方通常不在资源文件，在“颜色值被缓存了”或者“应用被 setColorMode 锁住了，系统切换根本没传进来”。先查覆盖状态，再查缓存，比反复改资源目录更快。