移动端深色模式切换失败的90%原因是变量未定义在:root、prefers-color-scheme未同步初始化、第三方组件样式优先级不足；必须统一在:root声明双主题变量、用JS提前设置data-theme、提高第三方组件选择器优先级、所有var()带fallback、声明color-scheme。
移动端深色模式切换失败，90% 是因为变量没挂到 :root、prefers-color-scheme 媒体查询没同步初始化、或者第三方组件被样式优先级绕过——不是写法不对，是三处硬伤同时存在。
必须把所有变量定义在 :root，不能写在 .dark 或 body 里
CSS 变量靠继承传播，而只有 :root（即 <html> 元素）能保证全页面任意节点都读得到。写在其他选择器里，变量只在该选择器后代生效，<input>、<button>、伪元素、Shadow DOM 内部都会 fallback 到初始值或透明。
-
.dark { --bg: #121212 }→ 只对.dark自身及其子元素有效，兄弟节点和表单控件拿不到 -
body { --text: #eee }→var(--text)在<html>上求值时根本找不到定义 - 正确写法：所有变量统一在
:root声明，默认值 + 深色覆盖两套都得有，漏一个就会崩
@media (prefers-color-scheme: dark) 必须配合 JS 同步初始化 data-theme
移动端闪屏（白→黑）的根本原因是：浏览器首次渲染时，prefers-color-scheme 还没读取完成，:root 变量已按浅色默认值渲染完毕；等媒体查询生效，才重绘——这个间隙在 iOS Safari 和 Android WebView 中尤其明显。
- 必须在
<head>内联轻量 JS，用window.matchMedia('(prefers-color-scheme: dark)')立刻检测并设置document.documentElement.setAttribute('data-theme', 'dark') - 所有关键样式规则要写两套：
[data-theme="dark"] .btn（防闪） +@media (prefers-color-scheme: dark) .btn（保语义） - 别指望服务端预判——首屏直出无法知道客户端系统设置，JS 初始化必须在 DOM 构建前完成
第三方组件主题失效，本质是选择器优先级不够
Ant Design、NutUI、Vant 这类库通常靠 JS 注入 .dark 类或动态改 :root 变量，和你的媒体查询规则容易打架：要么你的 CSS 被 reset，要么库的主题开关失效。
立即学习“前端免费学习笔记（深入）”；
- 覆盖时必须提高选择器优先级，例如用
html[data-theme="dark"] .nut-button，而不是简单写.nut-button - 禁用
!important——它会切断变量链，导致后续用户手动切换主题完全失效 - 查库文档是否提供
theme-changed事件，必要时监听并手动同步data-theme属性 - NutUI 的
.nut-theme-dark类需配合--nut-xxx变量使用，不能只加 class 不重载变量
所有 var() 必须带 fallback，且 color-scheme: light dark 不可省
变量未定义时，var(--bg) 不会报错，而是直接 fallback 到浏览器默认值（比如 transparent），背景、边框、阴影全崩，还很难定位。
- 每个
var()都要写 fallback：background: var(--bg, #ffffff)、color: var(--text, #333) -
color-scheme: light dark告诉浏览器你支持双模式，原生控件（<input>、<select>、滚动条）才会按主题渲染；没它，再完美的变量也白搭 - 旧版 Safari 不识别复合媒体查询（如
@media (max-width: 768px) and (prefers-color-scheme: dark)），只用单层@media (prefers-color-scheme: dark)并确保它写在默认:root之后
最易被忽略的其实是变量命名稳定性：别用 --light-bg/--dark-bg 这种平行命名，统一用 --bg-color——切换时才是“同一个值的不同状态”，否则 JS 主动切换和系统偏好就彻底割裂了。
