直接操作 document.documentElement.className 是最稳、最可控的主题切换方式，因其能确保 CSS 变量、伪元素及第三方组件正确响应，避免闪屏、失效与维护难题。
直接操作 document.documentElement.className 是最稳、最可控的方式，其他路径（如改 body 类、切 <link>、用 <template>）要么失效、要么闪屏、要么难维护。
为什么必须锁定 document.documentElement
所有主流深色模式、多品牌切换最终都落到根元素上——document.documentElement 是唯一能保证 CSS 变量、伪元素（::before/::after）、第三方组件（Ant Design、Bootstrap）响应的主题锚点。
常见错误现象：
-
document.body.classList.toggle('dark')：:root 变量不生效，background-image: var(--logo-src)仍加载默认图 - 给某个 wrapper
div加 class：弹窗、Tooltip、Portal 渲染到 body 下的节点完全不受控 - 用
<link rel="stylesheet" href="dark.css">切换：CORS 静默失败、无 transition 动画、首屏白屏（FOUC）
实操建议：
立即学习“前端免费学习笔记（深入）”；
- 统一入口：只改
document.documentElement的 class 或data-theme属性 - 初始化时同步：读取
localStorage.getItem('theme')后立即写入根元素，不要等 DOMContentLoaded 之后再操作 - 服务端渲染（SSR）场景下，HTML 模板中直接输出
<html data-theme="dark" class="dark">，避免客户端 JS 注入前的样式空白
classList.add/remove 比 className = 'xxx' 更安全
element.className = 'dark' 会清空所有已有类名，对编辑器、表单、富文本等复杂组件是灾难性操作。
正确做法是用 classList API：
-
document.documentElement.classList.add('dark')—— 显式添加，不干扰其他类 -
document.documentElement.classList.remove('dark')—— 精准移除，不影响brand-a或loading等并存状态 - 避免裸用
toggle()：它不检查当前状态，多脚本并发时易错位；应先contains('dark')再决定 add/remove
兼容旧版 IE（如需）：
- IE10+ 支持
replace()，适合互斥状态（如editing/preview） - IE9 只能手动字符串处理：
el.className = el.className.replace(/\bdark\b/g, '') + ' light'
CSS 变量 + :root 是主题切换的底层支撑
光切 class 不起作用。CSS 必须通过变量定义可变样式，并靠选择器权重自然覆盖。
基础结构示例：
:root {
--bg: #fff;
--text: #333;
--primary: #007bff;
}
.dark :root {
--bg: #1a1a1a;
--text: #e6e6e6;
--primary: #28a745;
}
body {
background-color: var(--bg);
color: var(--text);
}
关键细节：
- 变量命名要有语义层级，如
--color-primary、--space-md，别用--c1这类缩写 - 图片路径可用
var(--logo-src)，但注意路径相对于 CSS 文件位置解析，不是 HTML - 避免
!important覆盖变量值——它会让后续三态（auto/dark/light）扩展变得不可控 - 动画支持：在
body或html上加transition: background-color 0.2s即可平滑过渡
localStorage 同步与初始化防错
用户手动修改 localStorage、服务端直出 class、多个页面共享 storage，都会导致状态错位。
稳妥流程是「读 → 判 → 设 → 存」四步闭环：
- 读取：
const saved = localStorage.getItem('theme') - 判断：
const isDark = document.documentElement.classList.contains('dark') - 设置：
isDark ? document.documentElement.classList.remove('dark') : document.documentElement.classList.add('dark') - 存储：
localStorage.setItem('theme', isDark ? 'light' : 'dark')
容易被忽略的点：
- 系统偏好变更（
prefers-color-scheme）需单独监听，不能依赖 localStorage 值 - 多个标签页间 theme 不同步：用
storage事件监听其他页变更，触发本页更新 - SSR 页面首次渲染时，JS 尚未执行，
data-theme和 class 必须由模板直出，否则必闪屏
