CSS兼容深色模式的平滑主题颜色切换

深色模式切换功能如今已成为网站的标配特性。有趣的是，许多开发者在实现时都卡在了同一个环节——主题颜色切换时缺乏平滑过渡效果，颜色是“啪”一下直接跳变，没有任何动画衔接。问题究竟出在哪里？其实原理并不复杂，但细节中的坑确实不少。

核心要点就一句话：别想着给 --bg-color 这类自定义属性直接加 transition，那是无效操作。你必须把过渡效果写在浏览器能识别的原生属性上，比如 background-color，并且要确保起始值和结束值都是实实在在、可计算的具体颜色值。

为什么 transition: --bg-color 0.3s 完全不起作用

这是很多人踩的第一个坑。CSS 规范明确规定：自定义属性不支持动画。你写 transition: --bg-color 0.3s，浏览器会直接忽略，既不报错也不执行。真正能实现过渡效果的，永远是那些原生属性：background-color、color、border-color、opacity，仅此而已。

• 可以这样理解：--bg-color 只是一个占位符，实际渲染时会被替换成具体颜色值。过渡动画发生在这些具体值之间。
• 如果颜色值的一端是 transparent 或 inherit，插值计算就会中断，甚至直接产生跳变。
• 有人会想到用 @property 声明可动画变量？Chrome 从 101 版本开始支持，但 Safari 至今仍不支持，生产环境不建议使用。

transition 必须写在默认状态规则中

另一个常见错误是只在 .dark 类里写 transition。结果切换时该闪还是闪。为什么？因为默认状态下浏览器根本没有定义过渡行为。当你从“无过渡”的默认状态切换到“有过渡”的深色状态时，第一帧画面就是直接跳过去的。

• 正确做法是把 transition 写在默认状态的规则里，比如 body 上：body { background-color: #ffffff; color: #333333; transition: background-color 0.35s ease-in-out, color 0.35s ease-in-out; }
• .dark 类里只需要提供目标值：background-color: #121212; color: #e0e0e0;
• 所有参与过渡的属性，在默认状态和 .dark 状态里，都必须写死具体的颜色值，不能留空，也不能用 initial。这是实现平滑主题切换的基本规则。

手动切换时 class 比 data-theme 更可靠

使用 document.documentElement.classList.toggle('dark') 是最轻量、最可控的深色模式切换方式。data-theme="dark" 本身不会触发样式重算，需要配合选择器（如 [data-theme="dark"]）才能生效，且这个选择器的优先级必须高于 :root 中的默认声明。

• 正确的选择器写法是 html[data-theme="dark"] 或 [data-theme="dark"]，像 html[data-theme="dark"] :root 这种写法不会生效。
• 忘记同步 class 和 localStorage？刷新页面后主题设置一定会丢失。
• 初始化阶段最容易出现闪屏。关键是在 DOM 加载前就把 class 设置好，否则首屏白底闪一下再变黑，用户体验很差。

移动端闪屏主因是初始渲染时机不对

这个问题在 iOS Safari 和 Android WebView 上尤其明显。系统偏好读取是异步的，但 HTML 和 CSS 解析是同步的。:root 里默认的 --bg: #fff 已经完成了首次渲染，等媒体查询匹配上才去重绘，时间差就这样产生了。

• 必须在 里内联一段轻量 JS，用 matchMedia('(prefers-color-scheme: dark)') 同步检测系统深色模式偏好。
• 检测到后立即给 添加 data-theme="dark" 或对应 class。千万别等到 DOMContentLoaded 事件后再操作，到那时已经来不及了。
• 所有主题变量必须在顶层 :root 中先声明默认值。使用变量时必须带上 fallback 值：background-color: var(--bg, #ffffff)。

说到底，真正实现平滑主题颜色切换的难点，不在于写那一行 transition，而是要确保变量已经定义、class 已经存在、transition 已经提前声明、初始颜色值可以插值计算。这几个环节，漏掉任何一个，结果就只剩下颜色跳变了。