真正可用的方案是“系统偏好初始化 + JS 主动控制 + localStorage 持久化”三者组合：prefers-color-scheme 仅被动响应系统设置，无法保存用户选择或触发JS逻辑，需配合 data-theme 属性与 localStorage 实现可靠切换。
亮暗色主题自动切换不能只靠 prefers-color-scheme 媒体查询 —— 它只响应系统设置变化，不保存用户手动选择，也不触发 JS 逻辑。真正可用的方案是“系统偏好初始化 + JS 主动控制 + localStorage 持久化”三者组合。
为什么 prefers-color-scheme 不能单独用
它只是 CSS 层的被动响应机制，比如你写 @media (prefers-color-scheme: dark) { :root { --bg: #121212; } }，页面加载时会按系统设置生效，但以下情况它完全失效：
- 用户点击按钮切到暗色，系统仍是亮色 →
prefers-color-scheme不变，样式不更新 - 用户切完暗色后关掉页面，下次打开还是亮色 → 它不读写
localStorage，无法恢复上次选择 - 你想加一个“跟随系统”选项，需要 JS 主动监听系统变更并同步状态 →
prefers-color-scheme本身不提供事件回调
document.documentElement.setAttribute('data-theme', ...) 的正确写法
这是最稳定、兼容性好、且语义清晰的主题控制方式。关键点不是“能不能设”，而是“设什么值、怎么匹配”：
- CSS 中必须用
[data-theme="dark"]这类属性选择器，且值要和 JS 设置的**完全一致**（大小写、连字符、引号都算） - 错误示例：
document.documentElement.setAttribute('data-theme', 'dark')对应 CSS 写了[data-theme="theme-dark"]→ 不匹配，样式不生效 - 推荐统一用
light/dark，避免冗余前缀；CSS 中就写:root[data-theme="dark"] - 不要用
removeAttribute('data-theme')回退到默认 —— 显式设为light更可控，也方便后续扩展多主题
初始化时如何安全读取并应用主题
页面首次加载必须在 CSS 解析完成前把 data-theme 设上，否则会闪屏（先亮后暗或反之）。不能等 DOMContentLoaded，更不能等 Vue/React 挂载：
立即学习“前端免费学习笔记（深入）”；
- 把初始化逻辑放在
<script>标签里，放在</head>前或<body>开头 - 优先读
localStorage.getItem('theme')，有值就直接设data-theme - 没值时再查系统偏好：
window.matchMedia('(prefers-color-scheme: dark)').matches，结果设为dark或light - 设完立即调用
localStorage.setItem('theme', value)，保证后续刷新能读到
切换时别踩 style.setProperty() 的坑
有人想绕过 data-theme，直接用 JS 改 :root 变量，比如 document.documentElement.style.setProperty('--bg', '#121212') —— 这在变量少时可行，但实际项目中容易出问题：
- 大量变量逐个
setProperty会阻塞主线程，尤其在低端设备上造成卡顿 - 一旦漏设某个变量（比如忘了
--border-color），对应组件颜色就回退到初始值，UI 错乱 - 无法利用 CSS 层叠优势：
[data-theme="dark"]下所有变量一次定义，JS 只需切一个属性，维护成本低 - 跟
prefers-color-scheme兜底逻辑冲突 —— 后者依赖选择器作用域，不是内联 style 能覆盖的
真正要小心的是初始化时机和 data-theme 值的严格一致性；其余都是围绕这两点展开的逻辑补全。变量定义位置、命名规范、过渡动画这些，反而属于次要优化项。
