如何通过 CSS 变量与 JS 配合实现一键切换全站暗黑模式的主题功能
作者：袖梨
2026-06-26
应使用window.matchMedia('(prefers-color-scheme: dark)')初始化检测并监听change事件，配合document.documentElement.style.setProperty()动态设置CSS变量，同时通过data-theme属性和localStorage持久化用户选择，确保首屏渲染即生效、系统切换实时响应且无视觉闪烁。
直接用 document.documentElement.style.setProperty() 设置 CSS 变量是最简单可靠的方式，但必须配合用户偏好检测、持久化存储和 class 切换逻辑，否则会出视觉闪烁、丢失状态或覆盖系统设置等问题。
如何正确读取并响应系统暗黑模式偏好
CSS 变量本身不触发媒体查询，JS 需主动监听 prefers-color-scheme 变化，不能只靠初始化时查一次。
- 用
window.matchMedia('(prefers-color-scheme: dark)')获取当前系统偏好，.matches返回布尔值 - 必须调用
.addEventListener('change', handler)监听后续系统主题切换（比如 macOS 用户在控制中心实时切主题） - 不要仅依赖
navigator.userAgent或screen.colorDepth等不可靠字段判断暗色模式
如何用 JS 安全地写入和批量更新 CSS 变量
直接操作 :root 的 style 属性最可控，避免污染全局或误改第三方组件的变量。
- 统一通过
document.documentElement.style.setProperty('--bg-color', '#121212')设置，不要用style.cssText全量重写（会清空其他动态样式） - 把明/暗两套变量值预先定义为 JS 对象，例如
const themes = { light: { '--bg-color': '#fff', '--text-color': '#333' }, dark: { ... } }，切换时遍历赋值 - 避免在循环中频繁触发重排，可先收集所有
setProperty调用，再统一执行（现代浏览器对此优化较好，但大量变量时仍有差异）
为什么必须用 class 控制根元素而不能只靠 CSS 变量
CSS 变量无法独立控制选择器权重或条件渲染，纯靠变量会导致部分样式无法回退（比如 img 的 filter: brightness(0.8) 在亮色下不该生效）。
立即学习“前端免费学习笔记（深入）”；
- 给
<html>添加class="theme-dark"或class="theme-light"，CSS 中用.theme-dark { --bg-color: #121212; }+.theme-dark img { filter: none; }组合控制 - 切换时先移除旧 class 再添加新 class，防止 class 堆积（如同时存在
theme-dark theme-light） - localStorage 中只存主题类型字符串（
'dark'或'light'），读取后立即同步到 class 和变量，避免 JS 与 DOM 状态不一致
常见错误：切换时页面闪动或部分区域未更新
根本原因是 CSS 变量更新时机与浏览器渲染流程错位，尤其在首次加载或跨设备同步时。
- 不要在
DOMContentLoaded之后才读 localStorage 并设变量——应尽早（如 script 放 head 里）读取并document.documentElement.classList.add()，让 CSS 引擎初始渲染就按目标主题走 - 确保所有颜色相关样式都基于变量（如
background-color: var(--bg-color); color: var(--text-color);），避免硬编码值残留 - 若用 Web Components 或 Shadow DOM，需在每个 shadowRoot 内手动设置变量，
:root的变量不会穿透
最易被忽略的是系统偏好监听的注册时机——如果在 React/Vue 组件挂载后才加 matchMedia 监听器，用户中途切系统主题时，页面不会响应；必须在 JS 执行早期就绑定，且确保卸载时调用 .removeEventListener 避免内存泄漏。
