最稳方案是操作document.documentelement：所有主流深色模式最终都落在此处，改body或内层容器会导致css变量、伪元素及第三方组件样式失效；必须配合:root变量定义、localstorage持久化及内联初始化脚本防闪屏。
直接改 document.documentElement 的 class 最稳
所有主流黑暗模式方案最终都落到根元素上，document.documentElement 是唯一可靠锚点。改 body 类名会漏掉 :root 变量、伪元素、部分第三方组件样式；改内层容器更不行——主题得覆盖全页面。
常见错误是把 dark 类加在 body 或某个 wrapper div 上，结果 CSS 变量没生效、::before 背景还是白的、第三方 UI 库（比如 Bootstrap 或 Ant Design）主题不响应。必须锁定 document.documentElement。
- 正确写法：
document.documentElement.classList.toggle('dark') - 配合 localStorage 保存状态：
localStorage.setItem('theme', 'dark') - 初始化时读取并同步：
if (saved === 'dark') document.documentElement.classList.add('dark')
classList.toggle() 适合二元切换，但别裸用
单按钮切换深/浅色时，classList.toggle('dark') 看似简洁，但容易埋坑：用户手动修改了 localStorage、服务端渲染初始类名已存在、或多个脚本同时操作 classList，都会导致状态错位。
稳妥做法是先判断再操作，而不是无脑 toggle：
- 读取当前状态：
const isDark = document.documentElement.classList.contains('dark') - 显式设置：
isDark ? document.documentElement.classList.remove('dark') : document.documentElement.classList.add('dark') - 同步 storage：
localStorage.setItem('theme', isDark ? 'light' : 'dark')
这样逻辑清晰，调试时一眼看出当前状态，也方便后续扩展三态（比如 auto、dark、light）。
CSS 变量 + :root 选择器才是主题切换的底层支撑
光切 class 没用，CSS 必须配合变量定义。所有颜色、背景、边框、阴影等主题相关属性，必须通过 :root 中的 CSS 变量声明，并用 .dark :root 或 .dark[data-theme] 覆盖。
错误示范：直接在 .dark .btn 里重写所有颜色 —— 维护成本爆炸，且无法被 JS 动态读取或复用。
- 基础写法：
:root { --bg: #fff; --text: #000; } - 深色覆盖：
.dark :root { --bg: #1a1a1a; --text: #e6e6e6; } - HTML 元素用变量：
background-color: var(--bg); color: var(--text) - 避免用
!important，靠选择器权重和变量继承自然生效
切换时的 FOUC 和 SSR 兼容要点
页面首次加载时，JS 还没执行，class 没加，CSS 变量还是默认值，会闪一下白屏（FOUC）。服务端渲染（如 Next.js、Nuxt）更麻烦：HTML 已带 class，但 JS 初始化又重复操作。
关键不是“怎么切”，而是“什么时候切”：
- 把主题判断逻辑提到
<script></script>标签最开头，甚至内联在 HTML head 里 - 服务端需输出对应 class：
，JS 初始化时跳过 add/remove - 用
data-theme属性替代纯 class（如data-theme="dark"），语义更强，也方便媒体查询联动（@media (prefers-color-scheme: dark)） - 动画过渡要加在 body 或 root 上：
transition: background-color 0.2s, color 0.2s，别只写个别元素
真正难的不是切一次，而是让切换在 SSR、CSR、用户手动改系统偏好、localStorage 被清空等所有边界场景下都不崩——变量定义、状态读取、DOM 操作这三步缺一不可，少一个就露馅。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
