prefers-color-scheme 是浏览器原生支持的媒体查询，用于响应系统深色/浅色设置，首次加载时生效，需配合 matchMedia 监听运行时变化，并通过 data-theme 统一管理用户手动与系统自动两种模式的优先级。
怎么用 prefers-color-scheme 自动适配系统主题
现代浏览器（Chrome 76+、Firefox 96+、Safari 12.1+）原生支持通过 prefers-color-scheme 媒体查询响应系统级深色/浅色设置。它不是“开关”，而是“感知器”——用户没手动点按钮，页面也能默认变暗。
关键点：它只在首次加载时生效，不监听运行时系统切换（除非刷新）。若需实时响应，得配合 window.matchMedia 监听变化。
- 基础写法：
@media (prefers-color-scheme: dark) { body { background: #121212; color: #e0e0e0; } } - 必须写在 CSS 中（
<style>或外链 CSS），不能用 JS 直接读取该媒体查询的布尔值 - 若用户系统设为“自动”且当前是夜间时段，部分系统（如 macOS）会触发
dark；但 Windows 10/11 的“自动”模式不暴露给网页，仅返回当前手动设定值
手动切换时，用 data-theme 控制根节点状态
纯靠系统判断不够灵活——用户可能系统是亮色，但想临时切暗色看文档。这时需要一个可写入 DOM 的“权威状态源”，data-theme 是最轻量、语义清晰的选择。
不要用 class="dark" 单独控制，也不要用 body 作为样式锚点（影响 scoped 样式复用和 Shadow DOM 隔离）。
立即学习“前端免费学习笔记（深入）”；
- 初始化时优先读 localStorage：
document.documentElement.dataset.theme = localStorage.getItem('theme') || 'auto' - 切换函数里同时改
dataset.theme和localStorage，例如：function setTheme(theme) { document.documentElement.dataset.theme = theme; localStorage.setItem('theme', theme); } - CSS 中这样写：
[data-theme="dark"] { --bg: #121212; --text: #e0e0e0; } [data-theme="light"] { --bg: #ffffff; --text: #333333; }
matchMedia('(prefers-color-scheme: dark)') 怎么监听系统变更
如果用户在页面开着时去系统设置里改了深色模式，你想让页面立刻响应，就得监听 matchMedia 的 change 事件。但它不会触发你自定义的“手动切换逻辑”，得自己桥接。
- 监听写法：
const darkModeMedia = window.matchMedia('(prefers-color-scheme: dark)'); darkModeMedia.addEventListener('change', e => { if (document.documentElement.dataset.theme === 'auto') { setTheme(e.matches ? 'dark' : 'light'); } }); - 注意：
e.matches是布尔值，true表示系统当前处于深色模式 - 必须在
setTheme里加判断：只当当前是auto模式时才响应系统变更；否则用户手动选的“亮色”会被系统自动覆盖 - 兼容性：IE 不支持，但 IE 本身不支持
prefers-color-scheme，可忽略
为什么别用 class 切换 + !important 覆盖样式
常见错误是给 body 加 class="dark-mode"，再用一堆 !important 强行覆盖原有颜色声明。这会导致三类问题：
- CSS 优先级混乱：后续维护者很难理清哪条规则生效，尤其引入第三方组件库时容易冲突
- 无法利用 CSS 变量做主题内插值（比如暗色下按钮 hover 透明度微调）
- 服务端渲染（SSR）或静态生成（如 Hugo/Jekyll）时，JS 还没执行，
class没加，首屏闪白/闪黑 - 正确做法是：把所有主题相关颜色抽成
--bg、--text等 CSS 变量，在:root和[data-theme]下统一定义，JS 只管切换data-theme值
真正麻烦的不是加开关，而是处理「系统自动」和「用户手动」两种意图的共存与优先级。多数人卡在监听系统变更后无条件覆盖用户选择，结果用户点了暗色又自动切回亮色——那个瞬间的错乱感，比没有夜间模式还伤体验。
