主题切换失效的根源是选择器权重、dom操作目标与css变量作用域三者未对齐：权重叠加导致部分样式被覆盖，html/body根节点错位使规则不匹配，变量未在统一上下文中重定义引发局部失效。
选择器权重在主题切换中会意外叠加
很多人切完主题发现按钮变黑了但边框还是亮色，或者深色模式下文字颜色没变——不是变量没更新，而是选择器权重被悄悄拉高了。比如你写了 html[data-theme="dark"] .button--primary，又在另一个文件里加了 .app--dark .button--primary，后者权重更高，覆盖了前者定义的 --btn-bg，但漏写了 --btn-border，结果边框就回退到默认值。
常见错误现象：:root.dark 和 body.theme-dark 同时存在；.theme-dark .card 和 html[data-theme="dark"] .card 并存；第三方 UI 库自带的 .dark .btn 与你的主题规则冲突。
- 同一组件的多个主题规则必须放在同一 CSS 文件里，避免加载顺序导致后加载的覆盖前者的部分变量
- 禁止混用
class和data-属性做主题控制，它们是两套独立机制，不会自动映射 - 用 DevTools 的“Computed”面板点开某个元素，看
--bg-color值是从哪条规则来的，而不是只查“Styles”里的声明
HTML根节点操作对象错位导致样式不生效
CSS 规则写的是 html.dark，JS 却去改 document.body.classList.toggle('dark')，那整个规则压根不会触发。浏览器匹配选择器时，是严格按 DOM 节点层级找的，html 和 body 完全不是一回事。
容易踩的坑：body.dark .button 规则下操作 document.documentElement；用了 :root { --color: red } 却把 dark class 加在 body 上；Tailwind 的 dark: 前缀依赖 html.dark 或 body.dark，但没确认自己项目用的是哪个。
- 先检查现有 CSS 主题规则的选择器主体：以
html、body还是:root开头 - 统一挂载点：推荐全部用
document.documentElement（即html标签），它能影响::before、fixed元素、SVGfill和<meta name="color-scheme"> - 别用
className = 'dark'赋值，它会清空所有已有 class，比如js-initialized或框架注入的hydrated
BEM修饰符和主题变量混用引发语义断裂
写 .button--dark 看似简单，但实际让主题变成了组件的“状态”，而不是页面级上下文。一个按钮不该知道自己属于什么主题，它只该知道自己是“主要按钮”或“危险操作”。一旦你把主题逻辑塞进 BEM 修饰符，所有组件都要为每个主题重复写一遍样式，变量联动失效，PurgeCSS 还可能误删未显式出现的类名。
正确做法是让 data-theme 控制变量作用域，BEM 修饰符只表达组件角色。例如：html[data-theme="dark"] .button--primary { --btn-bg: #333; }，而不是 .button--dark { background: #333; }。
- 所有变量引用必须带 fallback：
background-color: var(--btn-bg, #007bff);，防止 JS 未执行或 SSR 首屏白屏 - 禁止在修饰符里再嵌套修饰符，如
.button--dark--large，这会破坏语义且无法维护 - 如果用了
prefers-color-scheme自动回退，确保@media规则加了:not([data-theme])条件，否则用户手动选的主题会被系统偏好覆盖
CSS变量重定义范围失控导致局部失效
你在 :root.dark 里改了 --text-color，却漏掉了 --card-bg 和 --input-border，结果卡片背景还是白色，输入框边框仍是浅灰。这不是 JS 没执行，而是变量没在正确上下文中覆盖。
更隐蔽的问题是：多个主题文件分开打包（theme-light.css/theme-dark.css），加载顺序不确定，后加载的 CSS 覆盖了前者的变量定义；或者用了 !important 写死变量值，导致后续 style.setProperty() 完全失效，DevTools 里都看不到变化。
- 主题配置应对象化管理，用 JS 批量注入：
Object.entries(theme).forEach(([k, v]) => document.documentElement.style.setProperty(k, v)) - 避免在 JS 中拼接完整 CSS 字符串注入
<style></style>，违反 CSP 且无法被 DevTools 追踪 - 所有可变属性（颜色、间距、圆角）必须通过
var(--xxx)引用，不能写死值；否则主题切换等于白干
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
