如何利用 window.matchMedia 根据用户系统偏好自动切换网站的深色皮肤

作者：袖梨 2026-07-27

window.matchMedia 能实时响应系统深色模式切换，但必须显式绑定 change 事件监听器；直接读取 matches 属性仅获当前快照，不自动更新；需配合 CSS @media 和客户端安全执行以避免闪动与内存泄漏。

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 修改而触发