暗黑模式切换必须操作document.documentElement，因为只有HTML根元素才能影响:root变量、伪元素、滚动条等全局样式；body上设置class或data-theme无法生效。
暗黑模式切换为什么必须用 document.documentElement 而不是 body
因为暗黑模式需要影响整个页面根级样式（包括伪元素、:root 变量、字体抗锯齿等），body 上设的 class 或属性无法穿透到 :root，也无法被 @media (prefers-color-scheme) 动态覆盖。只有 document.documentElement 对应 HTML 元素，是 CSS 的真正根节点。
常见错误是把 dark class 加在 body 上，结果 :root[data-theme="dark"] 根本不匹配，变量没生效，切换后界面毫无反应。
- 正确做法：所有主题相关逻辑都操作
document.documentElement -
:root和html是等价选择，但用data-theme自定义属性比 class 更语义清晰，也方便 JS 判断 - 初始化时务必检查
localStorage，别直接硬编码为 light
data-theme 属性怎么和 CSS 变量联动才不翻车
CSS 变量本身不响应属性变化，必须靠属性选择器触发重计算。关键不是“设置变量”，而是“让变量作用域随属性切换而切换”。
典型翻车点：在 :root 里一次性声明所有变量，却不按 data-theme 分组；或者用了 [data-theme="dark"] 却忘了加 html 前缀，导致选择器权重不足。
立即学习“前端免费学习笔记（深入）”；
- 必须写成
html[data-theme="light"] { --bg: #fff; --text: #333; }和html[data-theme="dark"] { --bg: #1a1a1a; --text: #eee; } - 所有颜色、阴影、边框粗细等视觉变量，都要在这两组里显式定义，不能只写 dark 版本指望 fallback
- 避免在组件级 CSS 里重复写变量值，统一收口在
:root级联规则中
html {
background-color: var(--bg);
color: var(--text);
}
html[data-theme="dark"] {
--bg: #121212;
--text: #e0e0e0;
}
html[data-theme="light"] {
--bg: #ffffff;
--text: #333333;
}
切换按钮点击后样式不动？检查这三件事
用户点了按钮没反应，90% 是 JS 没真正更新 DOM 属性，或 CSS 选择器没命中。不是逻辑错，是链路断在某个环节。
- 确认 JS 执行了
document.documentElement.setAttribute('data-theme', 'dark')，而不是document.body.setAttribute(...) - 打开 DevTools → Elements 面板，看
html标签上是否实时出现了data-theme="dark"—— 没出现就是 JS 没跑或被 try/catch 吞了 - 在 Styles 面板里搜
html[data-theme="dark"]，看对应规则是否被划掉（invalid）或权重不够（比如被!important覆盖）
示例最小可行切换逻辑：
const toggleBtn = document.getElementById('theme-toggle');
const html = document.documentElement;
// 初始化
const savedTheme = localStorage.getItem('theme') || 'light';
html.setAttribute('data-theme', savedTheme);
toggleBtn.addEventListener('click', () => {
const current = html.getAttribute('data-theme');
const next = current === 'light' ? 'dark' : 'light';
html.setAttribute('data-theme', next);
localStorage.setItem('theme', next);
});
兼容系统偏好设置（prefers-color-scheme）时的优先级陷阱
用户手动切换后，如果再触发系统主题变更（比如 macOS 夜间模式开启），页面可能被强制切回系统偏好值——这不是 bug，是你没明确约定优先级。
原则只有一条：用户显式操作 > 系统偏好 > 默认值。但很多人漏掉「取消监听」，导致系统监听器不断覆盖用户选择。
- 初始化时用
window.matchMedia('(prefers-color-scheme: dark)')获取当前系统值，但仅用于 fallback，不直接设 theme - 一旦用户点过切换按钮，就用
localStorage记录，并在后续启动时忽略系统监听结果 - 如果真要响应系统变更（比如用户清空 localStorage 后），需调用
mediaQuery.addListener()并在 handler 里加判断：仅当 localStorage 为空时才更新
最简健壮初始化逻辑：
function initTheme() {
const saved = localStorage.getItem('theme');
if (saved) {
html.setAttribute('data-theme', saved);
return;
}
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
html.setAttribute('data-theme', isDark ? 'dark' : 'light');
}
实际项目里，data-theme 的值是否同步到 localStorage、是否拦截系统监听、CSS 变量有没有漏定义——这三个点只要一个没对齐，暗黑模式就会看起来“有时灵有时不灵”。 
