必须把 data-theme 设在 document.documentElement 上，否则伪元素、fixed 定位、SVG 填色和 contenteditable 区域都会失配；正确做法是在 <head> 内联脚本中立即读取 localStorage 或媒体查询设置 html[data-theme]，同步更新 <meta name="color-scheme">，CSS 中用 html[data-theme="dark"] 定义变量并为所有使用处提供回退值和 transition 声明。
必须把 data-theme 设在 document.documentElement 上，否则伪元素、fixed 定位、SVG 填色和 contenteditable 区域都会失配——这不是样式没生效，是变量根本没被继承到。
为什么 document.body.setAttribute('data-theme', 'dark') 是错的
表面上按钮点了颜色变了，但打开开发者工具检查 <html> 标签，会发现它根本没有 data-theme 属性；[data-theme="dark"] 选择器压根没匹配上。所有依赖 :root 的 CSS 变量（比如 var(--bg)）都只认 <html> 上的属性，因为 :root 就是 <html> 的别名。设在 body 上等于把开关装在了房间门上，却指望整栋楼的灯都响应。
如何正确初始化并持久化主题状态
页面刚加载时就闪一下亮色？那是等 DOM 加载完才写 data-theme 导致的。必须把初始化逻辑塞进 <head> 里的内联 <script>：
const saved = localStorage.getItem('theme');
const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const initialTheme = saved ?? (systemPrefersDark ? 'dark' : 'light');
document.documentElement.setAttribute('data-theme', initialTheme);
localStorage.setItem('theme', initialTheme);
// 同步 meta color-scheme，影响地址栏、表单控件等系统级 UI
document.querySelector('meta[name="color-scheme"]').setAttribute('content', initialTheme);
-
localStorage.getItem('theme')优先读取用户上次选择，不是“有就用”，而是“唯一可信源” -
window.matchMedia只查一次，作为 fallback，不能当主控逻辑 -
meta[name="color-scheme"]必须同步更新，否则 iOS Safari 地址栏还是亮色
切换按钮点击后该执行什么操作
不要调用 document.documentElement.style.setProperty() 逐个改变量，也不要用 JS 动态插入 <style> 标签——前者强制全量重绘，输入中卡顿明显；后者调试困难、易冲突、兼容性差。真正轻量且语义清晰的做法只有这一种：
立即学习“前端免费学习笔记（深入）”；
- 用
document.documentElement.dataset.theme = 'dark'或document.documentElement.setAttribute('data-theme', 'dark') - 立刻
localStorage.setItem('theme', 'dark') - 如果用了 checkbox 控件，同步更新其
checked状态
浏览器会自动响应 CSS 变量变化，无需手动触发重排或加 class。所有使用 var(--text)、var(--bg) 的地方都会平滑过渡——前提是你在 CSS 里写了 transition: background-color 0.2s, color 0.2s。
容易被忽略的 CSS 写法细节
写了变量不等于主题能切，关键在于选择器权重和变量调用是否全覆盖：
- CSS 中必须写
html[data-theme="dark"] { --bg: #121212; }，漏掉html前缀会导致权重不足，尤其在 Tailwind 或 Bootstrap 项目里直接被覆盖 - 所有可变视觉属性都要显式调用：
border-color: var(--border-color);、fill: var(--icon-fill);、caret-color: var(--text);—— contenteditable 元素光标颜色不会随color自动变 - 每个
var()都要带回退值：color: var(--text, #333);，否则变量未定义时显示浏览器默认黑底白字，直接不可用
主题切换不是“换个 class”，是建立一套从 HTML 属性 → CSS 变量 → 所有样式声明的链路，断掉任意一环，就会出现部分区域颜色错乱、编辑器光标消失、固定导航栏颜色滞留这类问题。
