必须用data-theme属性控制暗黑模式，因其可持久化用户选择、避免刷新丢失，且挂载在<html>上能确保CSS选择器精准命中、兼容SSR与第三方库；仅依赖prefers-color-scheme媒体查询无法响应手动切换且刷新即失效。
暗黑模式切换必须用 data-theme 属性控制，不能只靠 @media (prefers-color-scheme: dark) 媒体查询——后者只是系统偏好信号，不响应手动操作，刷新后必然丢失用户选择。
为什么必须把 data-theme 放在 <html> 上
挂 body 或其他元素会导致 CSS 选择器失效、伪元素（如 input::-webkit-inner-spin-button）无法命中、第三方 UI 库（Tailwind/Bootstrap）主题注入错乱。Safari 14–15 对嵌套媒体查询有 bug，但 html[data-theme="dark"] 稳定可靠。服务端渲染时也能直出该属性，避免客户端闪屏。
初始化 JS 必须写成：
document.documentElement.dataset.theme = "dark"
而不是 document.body.setAttribute("data-theme", "dark")。设空字符串清空时用 delete document.documentElement.dataset.theme，别设成 "light" 或 "" 字符串——CSS 里 [data-theme=""] 不会匹配空属性。
立即学习“前端免费学习笔记（深入）”；
localStorage 读写时机和 fallback 逻辑
首次加载必须在所有 CSS 加载前完成 data-theme 设置，否则页面先按默认亮色渲染，再切主题就会闪白/闪黑。最佳做法是内联一段 <script> 放在 <head> 最顶部、<link rel="stylesheet"> 之前：
const saved = localStorage.getItem('theme');
const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.dataset.theme = saved ?? (systemPrefersDark ? 'dark' : 'light');
-
saved是字符串，可能为"dark"、"light"或null；??运算符能正确处理null，但不能用||（空字符串会被转成 false） - 别在
DOMContentLoaded里才读取——太晚了 - 别 fallback 到
matchMedia().matches后不设值，否则data-theme属性不存在，CSS 规则完全不生效
CSS 中怎么写才能压过 @media (prefers-color-scheme: dark)
媒体查询优先级低于属性选择器，所以必须用 html[data-theme="dark"] :root 覆盖变量，而不是只写 @media。基础变量定义在 :root，暗色覆盖写在属性选择器里：
:root {
--bg: #fff;
--text: #333;
}
html[data-theme="dark"] :root {
--bg: #1e1e1e;
--text: #e0e0e0;
}
body {
background-color: var(--bg);
color: var(--text);
}
- 所有颜色相关属性（
border-color、box-shadow、svg fill）都必须用var(--xxx)，硬编码值会绕过主题系统 - 别在
[data-theme="dark"]里重写布局或字体大小——那不是主题该管的事 - 如果用了
currentColor，SVG 和图标会自动随--text变，比写死fill="#333"更省心
为什么 <meta name="color-scheme"> 必须同步更新
页面变暗了，但 Chrome 地址栏还是白的、iOS 输入框边框仍是浅灰——这是因为浏览器 UI 颜色由 <meta name="color-scheme"> 控制，它不会随 JS 自动更新。漏掉这步，视觉就割裂。
每次 JS 切换主题后，必须显式更新：
document.querySelector('meta[name="color-scheme"]').content = "light dark"
注意两点：
- 内容必须是
"light dark"，两个值都要写，不能只写"dark" - 初始加载时也要从
localStorage读一次再设，否则首屏不匹配 - Safari 支持最好，Chrome 93+ 开始支持，旧版忽略也不报错
最易被忽略的是：系统主题变更监听要用 window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...)，且监听必须在初始化之后立即注册，回调里要同步更新 dataset.theme 和 localStorage——否则用户在系统设置里切了深色，网页毫无反应。
