必须用document.documentElement.style.setProperty，因为它将变量注入CSSOM根作用域，确保所有var(--x)可读取；其他方式如body或元素级setProperty仅影响内联样式，无法更新全局CSS变量。
document.documentElement.style.setProperty 为什么必须用这个
因为只有改 document.documentElement.style，才能把变量注入到 CSSOM 的根作用域里，让所有 var(--primary-color) 都能读到新值。用 document.body.style.setProperty 或随便一个 element.style.setProperty 都无效——它们只影响内联样式，对全局 CSS 变量完全没感知。
常见错误包括：
- 写成
document.querySelector('html').style.setProperty—— 虽然选对了元素，但漏掉document.documentElement的标准引用方式，某些环境（如 SSR 后 hydrate 阶段）可能拿不到正确实例 - 在 Shadow DOM 里直接操作 document，得换成
shadowRoot.host.style.setProperty - 变量名少了一个短横线，比如传
'-primary-color'或'primary-color'，浏览器直接忽略，也不报错
:root 和 [data-theme="dark"] :root 的写法差异
别把主题变量分散写在多个选择器里，比如 .theme-dark { --bg: #111; }。这样变量只在该选择器作用域生效，子元素继承不到，var(--bg) 在 body 里就 fallback 了。
正确结构是：
立即学习“Java免费学习笔记（深入）”；
Java Maven Common
下载
Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。
- 所有变量统一定义在
:root中（保证初始值存在） - 深色主题覆盖用
[data-theme="dark"] :root，不是[data-theme="dark"]单独写 - 每个主题分支都**完整声明全部变量**，哪怕值和默认一样，否则未声明的变量会回退到继承值或 initial，导致颜色错乱
例如：
:root { --bg-color: #fff; --text-color: #333; }<br>[data-theme="dark"] :root { --bg-color: #1a1a1a; --text-color: #f5f5f5; }
切换时页面闪一下（FOUC）怎么压住
JS 还没跑完，浏览器已经按默认 CSS 渲染了一帧，等变量注入才重绘——这就是用户看到的“先白后黑”或颜色跳变。
关键不是等 DOMContentLoaded，而是让主题状态在 HTML 解析阶段就确定：
- 把同步脚本塞进
<head>：比如<script>document.documentElement.dataset.theme = localStorage.getItem('theme') || 'light';</script> - 服务端渲染时，直接输出带
data-theme的<html data-theme="dark"> - 禁用
@media (prefers-color-scheme)作为兜底逻辑——它触发晚于 HTML 构建，无法避免首次闪屏
setProperty 后颜色没变？优先检查这三处
变量设了、控制台没报错、DOM 上也看到 style 属性更新了，但页面就是不动。大概率卡在这几个细节上：
-
var(--primary-color)在 CSS 里根本没被任何规则引用，比如只定义了变量，但组件里写的是color: #333，而不是color: var(--primary-color) - 变量名拼错：大小写不一致（
--PrimaryColorvs--primary-color）、用了下划线（--primary_color）、或漏了双短横线 - 传的值不是字符串：
document.documentElement.style.setProperty('--bg-color', 0x111111)或{ r: 17, g: 26, b: 39 }都会静默失败，必须是'#111827'或'rgb(17, 26, 39)'
复杂点在于：伪元素（如 ::before）有时不会自动重绘，可临时加 element.offsetHeight 触发重排；更稳妥的做法是确保所有颜色路径都由变量驱动，不混用硬编码值。
