最轻量可靠的动态主题方案是watchEffect自动追踪theme ref并调用document.documentElement.style.setProperty写入带--前缀的字符串值，配合:root中var(--theme-bg, #fff)回退机制，支持运行时任意组合换肤且无闪烁。
直接用 document.documentElement.style.setProperty 写变量 + watchEffect 自动追踪，是最轻量、最可靠、切换无闪烁的方案。其他方式要么要刷新、要么维护两套样式、要么依赖构建时编译，都不符合“动态响应式”的核心诉求。
怎么用 watchEffect 监听主题变化并实时写入 CSS 变量
Vue 3 的 watchEffect 会自动收集它内部读取的响应式依赖，主题切换时无需手动触发，只要改了 ref 或 computed，它就立刻执行更新逻辑。
- 定义一个主题配置 ref，例如：
const theme = ref({ primary: '#409eff', dark: false }) - 在
setup中调用watchEffect，并在其回调里调用document.documentElement.style.setProperty - 注意所有值必须是字符串，
dark ? '#1e1e1e' : '#ffffff'没问题，但不能直接传布尔值或数字 - 推荐统一前缀（如
--theme-bg），避免和第三方库或浏览器原生变量冲突
为什么必须在 :root 上定义变量，且不能只靠 class 切换
只靠 .dark 类去覆盖 :root 变量，本质仍是静态预设——你得提前写好所有主题的 CSS 块。而真正“动态响应式”的关键，在于运行时能任意组合：比如用户拖动色盘选主色、系统夜间模式开关联动、甚至从接口拉取品牌色。这些场景下，CSS 类名根本无法穷举。
-
:root是全局作用域起点，所有元素默认继承，var(--theme-bg)才能随处生效 - 如果只用
.dark类，document.documentElement.classList.add('dark')后，你仍需在 CSS 里写死所有深色变量值，失去运行时灵活性 - 混合使用更稳妥：用
setProperty控制基础变量，再用.theme-dark类微调 SVGfill或filter等不支持变量的属性
怎么处理 CSS 变量未定义时的回退与兼容性
CSS 变量天然支持回退值（var(--theme-text, #333)），但很多人忽略两点：一是回退值不会被继承，二是旧版 Safari 对级联变量支持不一致。
立即学习“前端免费学习笔记（深入）”；
- 始终为
var()提供合理回退，比如color: var(--theme-text, #333)，避免变量未设置时文字不可见 - 不要在
var()里嵌套另一个未定义变量，如var(--theme-bg-light, var(--theme-bg))—— 第二个var在未定义时不会继续解析 - 若需兼容 iOS 14.5 以下 Safari，可加一层 class fallback：
body:not([data-css-vars]) { --theme-bg: #fff; }，并在初始化时补上data-css-vars - Element Plus 等组件库依赖特定变量名（如
--el-color-primary），务必按文档命名，否则主题不生效
最易被忽略的一点：CSS 变量本身不触发重排，但大量 setProperty 连续调用可能引发重绘抖动。实际项目中，应把相关变量聚合成对象批量更新，而不是每个变量单独调一次 setProperty。
