必须用data-theme控制根元素+CSS变量分层定义+localStorage持久化三者协同，缺一不可；其他方式会导致fixed元素、伪类、SVG填色等漏样式或闪屏。
直接换整套皮肤，不是改几个颜色或加个 class 就能成——必须用 data-theme 控制根元素 + CSS 变量分层定义 + localStorage 持久化三者咬死，缺一不可。其他方式（比如切换 <link>、改 body.className、模板里插值生成内联 style）都会在 fixed 元素、伪类、SVG 填色、第三方组件上漏掉样式，或者首次加载闪白/闪黑。
为什么不能只改 body.className 或写 <body class="dark">
Ant Design、Tailwind、Bootstrap 等库的暗色支持都依赖 html[data-theme="dark"] 这个选择器；body.dark 根本不触发它们的变量重计算。更关键的是：::before、::after、position: fixed 的弹窗、内联 SVG 的 fill 属性，全靠 :root 作用域下的变量，而 :root 永远绑定到 document.documentElement（即 <html>），不是 <body>。
常见错误现象：
-
document.body.classList.add('dark')后按钮变深了，但地址栏、滚动条、表单 placeholder 还是浅色 - 切换后 SVG 图标没变色，检查发现
fill写的是硬编码#333，没用var(--icon-fill) - 用户点了深色模式，刷新页面又回浅色——因为没存
localStorage，也没读取系统偏好
data-theme 必须设在 document.documentElement 上
这是唯一能让所有 CSS 变量全局生效、且被伪元素 / fixed 元素 / SVG 正确读取的位置。设错位置等于白干。
立即学习“前端免费学习笔记（深入）”；
正确写法：
document.documentElement.dataset.theme = 'dark';
// 或
document.documentElement.setAttribute('data-theme', 'dark');
错误写法：
document.body.setAttribute('data-theme', 'dark'); // html 标签上根本没这个属性
CSS 中必须带 html 前缀，否则权重不够、作用域错位：
/* ✅ 正确 */
html[data-theme="dark"] {
--bg: #121212;
--text: #e0e0e0;
}
<p>/<em> ❌ 错误：漏 html，可能被子选择器覆盖 </em>/
[data-theme="dark"] { --bg: #121212; }</p><p>/<em> ❌ 错误：:root 不是选择器容器，.dark 是独立 class </em>/
:root .dark { --bg: #121212; }
CSS 变量必须分层定义 + 显式引用
只定义不引用，等于没写；只引用不提供回退值，变量失效时直接回退到浏览器默认，UI 崩溃。
结构必须是：
:root {
--bg: #ffffff;
--text: #333333;
--border: #e0e0e0;
}
html[data-theme="dark"] {
--bg: #121212;
--text: #e0e0e0;
--border: #444444;
}
body {
background-color: var(--bg, #ffffff);
color: var(--text, #333333);
border-color: var(--border, #e0e0e0);
}
容易漏掉的引用点：
-
::before和::after的background、color、border-color -
input:focus、textarea::placeholder、select:disabled - 内联 SVG 的
fill和stroke（必须写成fill: var(--icon-fill)） - Font Awesome 图标需额外加
.fa { color: var(--icon-fill); }
初始化脚本必须塞进 <head> 内联执行
如果等 DOMContentLoaded 再读 localStorage，用户会先看到默认主题（比如白底），再“啪”一下跳变，这就是 FOUC（Flash of Unstyled Content）。必须抢在 CSS 解析前就设置好 data-theme 和 <meta name="color-scheme">。
标准内联脚本（放 <head> 最顶部）：
<script>
const saved = localStorage.getItem('theme') ||
(window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
document.documentElement.setAttribute('data-theme', saved);
document.querySelector('meta[name="color-scheme"]')?.setAttribute('content', saved);
</script>
注意两点：
-
<meta name="color-scheme">必须提前写在<head>里，否则querySelector找不到 - 服务端能直出
<html data-theme="dark">更稳，彻底绕过 JS 执行空窗期
最易被忽略的点：所有可变样式都得显式调用 var(--xxx)，且每个都要带回退值；data-theme 切换后不会自动重绘动画，需要手动加 transition，比如 background-color 0.2s。
