如何利用 CSS 变量配合 JS 实现一键切换全站暗黑模式的主题功能
直接调用 document.documentElement.style.setProperty() 来设置 CSS 变量，无疑是实现主题切换最直观、最可靠的方法。但这里有个关键前提：你必须把用户偏好检测、持久化存储和根元素 class 切换这套组合拳打好。否则，视觉闪烁、状态丢失，甚至不小心覆盖了用户的系统设置，这些问题都会接踵而至。
如何正确读取并响应系统暗黑模式偏好
CSS 变量本身并不会主动响应媒体查询，所以 Ja vaScript 必须承担起监听系统偏好变化的责任，而且不能只在页面初始化时检查一次就了事。
- 核心工具是
window.matchMedia('(prefers-color-scheme: dark)')，它的.matches属性会返回一个布尔值，告诉你当前系统是否处于暗色模式。 - 更重要的是，必须调用
.addEventListener('change', handler)来监听后续的系统主题切换。想象一下，当 macOS 用户直接在控制中心切换主题时，你的页面能否实时跟上？就靠这个监听器了。 - 切记，不要依赖
na vigator.userAgent或screen.colorDepth这类不可靠的字段来判断暗色模式，它们既不准确，也不实时。
如何用 JS 安全地写入和批量更新 CSS 变量
直接操作 :root（即 document.documentElement）的 style 属性，是控制范围最清晰、最不容易出错的方式，可以有效避免污染全局样式或误改第三方组件内部的变量。
- 统一使用
document.documentElement.style.setProperty('--bg-color', '#121212')进行设置。避免使用style.cssText进行全量重写，因为它会清空该元素上所有其他动态样式，风险太高。 - 一个高效的做法是：预先将明暗两套主题的变量值定义为 Ja vaScript 对象。例如：
const themes = { light: { '--bg-color': '#fff', '--text-color': '#333' }, dark: { ... } }。切换主题时，只需遍历对应主题的对象并逐一赋值即可。 - 虽然现代浏览器对频繁的样式更新优化得不错，但在需要更新大量变量时，仍应注意性能。理论上可以先收集所有
setProperty调用，再统一执行，以减少重排次数。
为什么必须用 class 控制根元素而不能只靠 CSS 变量
这是因为 CSS 变量本身无法独立控制选择器权重或实现条件渲染。如果纯粹依赖变量，会导致一些特定样式无法根据主题正确回退。举个例子，你可能只想在暗色模式下为 img 添加 filter: brightness(0.8)，在亮色模式下这个样式不应该生效，仅靠变量是实现不了这种条件逻辑的。
立即学习“前端免费学习笔记（深入）”；
- 正确的做法是：给
根元素添加诸如class="theme-dark"或class="theme-light"的类名。然后在 CSS 中，将变量定义和条件样式结合起来写：.theme-dark { --bg-color: #121212; } .theme-dark img { filter: brightness(0.8); }。 - 切换主题时，务必先移除旧的 class，再添加新的 class，防止出现
theme-dark theme-light同时存在的混乱情况，导致样式冲突。 - 在 localStorage 中，只存储主题类型的字符串标识（如
'dark'或'light'）。读取后，应立即同步到根元素的 class 和对应的 CSS 变量上，确保 Ja vaScript 状态与 DOM 表现完全一致。
常见错误：切换时页面闪动或部分区域未更新
这个问题的根源，通常是 CSS 变量更新的时机与浏览器的渲染流程产生了错位，在页面首次加载或跨设备同步主题时尤其明显。
- 不要在
DOMContentLoaded事件触发之后才去读取 localStorage 并设置变量——那就太晚了。应该尽可能早地（例如将脚本放在中并立即执行）读取存储的主题，并通过document.documentElement.classList.add()应用对应的 class，让 CSS 引擎在初始渲染时就直接使用目标主题的样式，从而避免“默认亮色闪现一下再变暗”的闪烁问题。 - 确保所有与颜色相关的样式都基于 CSS 变量（例如
background-color: var(--bg-color); color: var(--text-color);），彻底避免任何硬编码的颜色值残留，否则这些“钉子户”样式是不会随主题变化的。 - 如果你的项目中使用了 Web Components 或 Shadow DOM，需要注意，
:root上定义的 CSS 变量默认是不会自动穿透到 Shadow DOM 内部的。你需要在每个 shadowRoot 内部手动重新设置这些变量。
最后，一个最容易被忽略的细节是系统偏好监听的注册时机。如果在 React/Vue 组件挂载后才去添加 matchMedia 监听器，那么当用户在应用中途切换系统主题时，你的页面将毫无反应。务必在 Ja vaScript 执行早期就绑定好监听器。同时，在适当的时机（如组件卸载时）调用 .removeEventListener 来移除监听，避免潜在的内存泄漏问题。
