Vue 3 中需通过 matchMedia 监听系统暗色偏好并手动绑定 change 事件来动态更新 ,结合 watchEffect 统一管理用户开关与系统切换,确保 SSR 安全及初始值同步。

Vue 3 中不能直接用 watch 监听“暗黑模式”本身,因为系统暗色偏好不是响应式数据。真正要监听的是 matchMedia('(prefers-color-scheme: dark)') 的 matches 状态变化,再结合 watchEffect(更自然)或带清理的 watch 实现动态更新 <meta name="theme-color">。
监听系统偏好并响应更新
浏览器不提供响应式 API,需手动订阅 mediaQueryList 的 change 事件。推荐在 onMounted 中注册,在 onUnmounted 中取消,避免内存泄漏:
- 创建
matchMedia('(prefers-color-scheme: dark)')实例 - 用
addEventListener('change', handler)捕获切换事件 - 在 handler 中调用
document.querySelector('meta[name="theme-color"]').setAttribute('content', ...) - 首次执行时也应同步一次,确保初始值正确
配合 Vue 响应式状态统一管理
若项目已有暗色模式开关(如 isDark = ref(false)),可让系统监听与用户手动切换共用同一状态:
- 初始化时读取
matchMedia.matches赋给isDark - 用
watchEffect监听isDark变化,统一更新<meta>和 CSS 变量 - 这样无论用户点击按钮,还是系统自动切(如夜间自动启用暗色),
<meta theme-color>都能同步
设置正确的 theme-color 值
<meta name="theme-color"> 影响地址栏、PWA 启动屏等,建议按模式配不同颜色:
立即学习“前端免费学习笔记(深入)”;
- 浅色模式:常用
#ffffff或主品牌色(如#42b883) - 暗色模式:推荐深灰系,如
#121212、#1e1e1e,避免纯黑(#000000)导致视觉割裂 - 务必确保该
<meta>标签已存在于index.html的中,且有name="theme-color"
注意 SSR 和 DOM 可用性
服务端渲染时 document 不存在,所有 DOM 操作必须包裹判断:
- 使用
if (typeof document !== 'undefined')安全校验 -
matchMedia在 Node 环境会报错,也需同样保护 - 首次挂载时可先从
localStorage或 URL 参数恢复主题,再与系统偏好对齐


















