必须将所有主题变量定义在 :root 中，因其是唯一能确保全局继承的声明位置；@media 仅作系统级兜底，不可替代手动切换；js 切换须操作 document.documentelement.classlist 并同步 localstorage，否则导致闪屏、回退或控件样式不一致。

必须把所有主题变量定义在 :root 里，否则切换必然失效——这不是可选项，是 CSS 变量作用域的硬性限制。

为什么 :root 是唯一安全的声明位置

CSS 自定义属性靠继承传播，而只有 :root（即 元素）能确保任意元素通过 var(--bg-color) 正确读取。写在其他地方会断继承链：

• .dark { --bg-color: #121212; } → <input> 或兄弟节点未被包裹时，直接 fallback 到透明或浏览器默认值
• body { --text-color: #eee; } → 上求值时根本找不到定义
• Shadow DOM 内部不会继承外部 :root 变量，需在 :host 或 ::slotted 里手动传入

@media (prefers-color-scheme: dark) 只能当兜底，不能当开关

它只在页面加载和系统设置变更时触发，无法响应用户点击切换。漏掉这层认知，90% 的“深色模式”实际是半残废：

CSS婚礼策划服务机构宣传网站模板

CSS婚礼策划服务机构宣传网站模板是一款适合提供婚礼策划和婚庆服务机构宣传网站模板下载。提示：本模板调用到谷歌字体库，可能会出现页面打开比较缓慢。

下载

• 系统设为浅色，但用户想手动开深色？@media 完全无响应
• 刷新后状态丢失：它不读 localStorage，也不支持持久化
• iOS 13 以下 Safari 对该媒体查询支持不稳定，不能依赖它做唯一判断
• 必须放在所有 :root 默认声明之后，且不能嵌套在其他媒体查询内，否则旧版 Safari 直接忽略

JS 切换必须只操作 document.documentElement.classList

调用 document.documentElement.style.setProperty() 看似直白，实则破坏整套机制：

• 覆盖 @media 和 :root.dark 的声明逻辑，导致系统级切换失效
• 大量变量逐个设置会卡 UI 线程，尤其在低端设备上明显
• 新增一个颜色就得同步改 JS 和 CSS 两处，维护成本爆炸
• 正确做法是：给 加 class="dark"，让 CSS 规则自动重算

初始化必须早于首屏渲染，且联动 localStorage

页面闪屏（白底→黑底）几乎全是这个环节出问题。三步缺一不可：

• 在 <script></script> 标签内直接执行，不要等 DOMContentLoaded —— 那时首屏已渲染完毕
• 读取 localStorage.getItem('theme')，而非依赖 matchMedia 初始值
• 切换按钮点击后，同步执行 classList.toggle('dark') 和 localStorage.setItem('theme', newTheme)

漏掉任一环，用户刷新后主题就回退，或者原生控件（<input>、<select></select>）颜色不一致。

前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！