window.matchMedia 实现自动深色模式切换指南

本文深入解析了如何利用 `window.matchMedia` 实现真正可靠、无闪动、无内存泄漏的自动深色模式切换——它不只是简单读取系统偏好，而是强调必须显式绑定 `change` 事件监听才能实时响应系统主题变更，同时揭示了仅查一次 `matches` 的局限性、旧版 Safari 兼容陷阱、组件卸载时的监听器清理必要性，以及 CSS 媒体查询与 JS 逻辑协同工作的黄金法则；更关键的是，它直击 SSR/静态站点首屏闪动（FOUC）这一高频痛点，给出客户端安全执行与主题优先级（用户手动选择 > 系统偏好）的落地实践，帮你避开从初学者到资深开发者都常踩的“伪自动”深色模式坑。

window.matchMedia 能实时响应系统深色模式切换，但必须显式绑定 change 事件监听器——不加这句，页面加载后就再也不会感知系统主题变化了。

怎么判断当前系统是深色还是亮色

直接读取 matches 属性即可，它返回布尔值：

const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

注意：这个值只反映「当前快照」，不是实时状态。比如用户在页面打开后切到深色模式，isDark 不会自动变，除非你监听了 change 事件并重新读取。

• 不要用 document.body.classList.contains('dark') 来反推系统偏好，那只是你上次 JS 设置的结果
• 如果浏览器不支持 prefers-color-scheme（如旧版 Safari 或 IE），window.matchMedia('(prefers-color-scheme: dark)') 仍会返回一个对象，但其 media 属性值为 'not all'，可据此降级处理
• 避免同时查 light 和 dark 两个查询，只需查一个，另一个取反即可；查两个可能因浏览器实现差异导致逻辑冲突

如何监听系统主题切换事件

必须调用 addEventListener('change', handler)，且推荐在初始化时就绑定，而不是等用户点击按钮后再绑：

const media = window.matchMedia('(prefers-color-scheme: dark)');
media.addEventListener('change', e => {
  if (e.matches) {
    document.documentElement.setAttribute('data-theme', 'dark');
  } else {
    document.documentElement.setAttribute('data-theme', 'light');
  }
});

容易忽略的点：

• 旧版 Safari（≤13.1）不支持 addEventListener，需兼容 addListener 回退写法
• 如果组件卸载（如 React unmount、Vue destroy）而没移除监听器，会造成内存泄漏；务必在清理阶段调用 media.removeEventListener('change', handler)
• 该事件只在系统级主题变更时触发，不会因窗口缩放、刷新或 CSSOM 修改而触发

为什么 CSS 媒体查询 + JS 监听要配合使用

CSS 的 @media (prefers-color-scheme: dark) 能让首屏直出正确样式，但无法驱动 JS 逻辑（比如图表重绘、localStorage 记录、第三方库主题切换）；而 JS 的 matchMedia 可以触发这些行为，但不能替代 CSS 原生渲染性能。

• 默认把亮色变量写在 :root 顶层，深色覆盖写在媒体查询内；反过来会导致深色模式下变量未定义
• 不要在组件内部重复定义同一组 CSS 变量，否则媒体查询无法穿透作用域生效
• 若同时支持手动切换和系统偏好，建议用 localStorage 存储用户选择，并优先级高于系统值；否则用户点了“切亮色”，系统一变又回暗色，体验断裂

最易被绕过的细节：服务端渲染（SSR）或静态生成站点首次加载时，window 不存在，matchMedia 会报错；需要确保相关逻辑只在客户端执行，且首次渲染前就完成主题判定，否则会出现闪动（FOUC）。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《window.matchMedia 实现自动深色模式切换指南》文章吧，也可关注golang学习网公众号了解相关技术文章。