黑夜模式实现：CSS变量与媒体查询应用

本文深入解析了如何利用 CSS 的 `prefers-color-scheme` 媒体查询与自定义属性（CSS 变量）协同实现优雅、可靠且符合现代 Web 最佳实践的黑夜模式自动适配——它原生轻量、无闪屏，能随系统深色/浅色设置实时响应，但仅作为“默认兜底”而非万能方案；文章强调必须通过语义化变量抽离样式、用 `data-theme` 属性实现用户手动切换与系统偏好之间的优先级分层（用户选择 > 系统设置 > 默认值），并借助 `matchMedia` 监听系统主题动态变更，最终构建出可维护、可降级、边界清晰的主题管理系统，直击多源信号冲突这一前端主题切换中最易被忽视却最棘手的核心难题。

如何用 prefers-color-scheme 自动适配系统主题

系统级深色模式开关一开，网页就该跟着变，不用用户点按钮——这是最省事也最符合直觉的做法。prefers-color-scheme 就是干这个的，它不是 JavaScript 行为，而是纯 CSS 媒体查询能力，原生、轻量、无闪屏。

关键点在于：它只响应系统设置，不记录用户手动选择；如果用户在亮色系统里硬要网页变暗，它帮不上忙。所以它适合做「默认兜底」，不能当唯一方案。

• 写法必须是 @media (prefers-color-scheme: dark) { ... }，括号和冒号缺一不可，漏空格或写成 prefers-dark 会直接失效
• 它支持 light / dark / no-preference 三种值，但实际只用前两个就够了
• Chrome 76+、Firefox 67+、Safari 12.1+ 支持，iOS 13+/Android 10+ 系统设置生效，旧版 Safari（如 iOS 12）会忽略整条规则，安全降级

为什么必须用 CSS 自定义属性（--color-bg）而不是直接写死颜色

硬编码 background: #121212 看似简单，但一旦要支持「系统自动 + 用户手动切换」双模式，立刻崩盘：你得同时维护两套完全重复的样式块，改一个颜色要同步改七八处，还容易漏。

用 CSS 变量把颜色抽出来，所有样式都引用变量，只需在根节点（:root）或特定作用域里批量重置变量值，样式层完全不动。

• 声明变量写在 :root 下：:root { --color-bg: #ffffff; --color-text: #000000; }
• 暗色模式覆盖：@media (prefers-color-scheme: dark) { :root { --color-bg: #121212; --color-text: #e0e0e0; } }
• 变量名建议带语义，比如 --color-surface 比 --bg-1 更易维护；避免用 black/white 这类绝对词，因为暗色模式未必真用纯黑

用户手动切换时，如何避免 prefers-color-scheme 覆盖用户选择

系统设的是亮色，用户却点了“我要黑夜模式”——这时候 @media (prefers-color-scheme: dark) 根本不触发，你得靠 class 控制。但更麻烦的是：用户切回“跟随系统”，你得让 CSS 变量重新交还给媒体查询接管。

核心思路是分层优先级：用户手动 > 系统偏好 > 默认值。用 class 加权是最稳的方式。

• 给 添加 data-theme="auto"（初始）、"light" 或 "dark"
• 在 CSS 中，html[data-theme="dark"] { --color-bg: #121212; } 的权重高于 @media 规则（因为同属普通选择器，但 class 更具体）
• 当用户选“自动”，删掉 data-theme 属性，让 :root 和媒体查询重新生效；不要设成 auto 再去匹配，那没意义
• JavaScript 切换时务必用 document.documentElement.setAttribute()，别用 className，否则 class 名冲突难管理

matchMedia 监听系统主题变化比轮询靠谱在哪

用户开着网页，中途去系统设置里切了深浅色——网页不会自动刷新，但你可以监听到。用 window.matchMedia 是唯一标准做法，轮询 getComputedStyle 查变量值既卡顿又不准。

• 监听写法：const mql = window.matchMedia('(prefers-color-scheme: dark)'); mql.addEventListener('change', e => { ... });
• 注意：IE 不支持 addEventListener 在 MediaQueryList 上，需用 mql.addListener() 兼容（但 IE11 已基本可弃）
• 监听回调里不要直接操作 DOM 样式，而是更新 data-theme 或重设 CSS 变量——保持逻辑和样式的分离
• 首次执行也要检查 mql.matches，否则页面加载时系统已是暗色，监听器却没触发

真正难的不是写几行 CSS 或 JS，而是想清楚「谁有最终决定权」：系统设置、用户点击、URL 参数、localStorage 记录……这些信号怎么排序、怎么同步、怎么降级。变量 + 媒体查询 + data-attribute 三层配合，少一层都容易在边界场景出问题。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《黑夜模式实现：CSS变量与媒体查询应用》文章吧，也可关注golang学习网公众号了解相关技术文章。