所有主题变量必须仅在 :root 下声明并用不同类名区分，如 :root.theme-dark；切换主题需操作 document.documentElement.classList，且确保样式中使用 var() 引用变量而非硬编码值。
怎么用 :root 声明主题变量才不会被覆盖
CSS 变量（--color-primary 这类）必须在 :root 或具体选择器里定义，但很多人写成 body { --color-primary: blue; }，结果换主题时新类名加在 html 上，旧变量还在 body 里生效——根本没被替换。
正确做法是所有主题变量只写在 :root 下，且不同主题用不同类名区分：
:root {
--color-bg: #fff;
--color-text: #333;
}
:root.theme-dark {
--color-bg: #1a1a1a;
--color-text: #eee;
}
-
:root是全局作用域，JS 切换document.documentElement.classList才能触发变量重计算 - 别在
body或组件内部重复声明同名变量，否则优先级混乱，调试时看到的值可能来自意外层级 - 如果项目用了 CSS-in-JS 或 Shadow DOM，
:root不会穿透，得在对应宿主节点上设变量
JS 切换主题时为什么 class 加上了但颜色没变
常见现象：执行了 document.documentElement.classList.add('theme-dark')，检查元素也看到 class 存在，但页面颜色还是亮色——大概率是 CSS 变量没用 var(--color-bg)，而是直接写了硬编码值，或者变量名拼错。
排查重点不是 JS 是否执行，而是变量是否被消费：
立即学习“前端免费学习笔记（深入）”；
- 检查用到颜色的地方是不是都用了
background-color: var(--color-bg);，而不是background-color: #fff; - 打开 DevTools 的“Computed”面板，搜
--color-bg，看当前值来自哪个:root规则，确认是否命中.theme-dark分支 - 如果用了
!important覆盖变量，比如color: var(--color-text) !important;，那主题切换后依然无效——!important不影响变量求值，只影响最终属性优先级
多个主题共存时怎么避免 CSS 变量冲突
当需要支持深色/高对比度/品牌定制三套主题，变量名一多就容易重名或漏覆盖，比如 --primary-color 在深色主题里指蓝色，在品牌主题里却指橙色，混在一起就乱。
推荐按主题前缀隔离变量：
:root {
--theme-default-primary: #007bff;
--theme-default-text: #333;
}
:root.theme-dark {
--theme-default-primary: #0056b3;
--theme-default-text: #f8f9fa;
}
:root.theme-brand-acme {
--theme-brand-acme-primary: #ff6b35;
--theme-brand-acme-text: #2c3e50;
}
- 变量名带主题前缀（
--theme-dark-、--theme-brand-acme-），避免跨主题污染 - 实际使用时统一走一层映射：
--color-primary: var(--theme-dark-primary, var(--theme-default-primary));，保证降级可用 - 不要靠 JS 动态生成整套 CSS 变量字符串再注入 style 标签——难维护、无缓存、SSR 不友好
SSR 或构建时主题预编译要不要删掉 :root 变量
服务端渲染或静态站点生成时，有人想“提前算好变量值”，把 var(--color-bg) 替换成 #fff。这看似省计算，实则破坏主题切换能力——JS 后续加类名，CSS 已经没变量可变了。
- 只要页面需要运行时主题切换，
var()就不能被构建工具（如 PostCSS 插件）静态展开 - 可以保留默认主题的
:root值，但必须留出.theme-dark等类名的覆盖规则，且确保它们在 CSS 文件里顺序靠后 - 如果首屏必须极致快，考虑用
prefers-color-scheme媒体查询做初始主题，再由 JS 接管后续切换——这样 SSR 输出的 HTML 已含对应类名，无需等 JS 执行才生效
最常被忽略的是：变量作用域和类名挂载位置必须严格匹配。document.documentElement 是唯一可靠锚点，任何往 body 或 wrapper div 上加主题类的操作，都会让 :root 变量失效——因为 :root 永远指向 html 元素，不认别的父容器。
