仅用@media (prefers-color-scheme: dark) 会导致闪屏、CSS变量未定义崩塌、第三方组件主题失效；需JS同步设置data-theme、媒体查询内完整声明变量并加fallback、提高第三方组件选择器优先级、真机测试WebView兼容性。
直接用 @media (prefers-color-scheme: dark) 能让页面自动响应系统深色设置，但真正在意体验的项目，必须解决三件事：系统切换时的视觉闪烁、CSS 变量未定义导致的样式崩塌、第三方组件主题被覆盖或失效。
为什么只写@media规则会闪屏
浏览器首次渲染时，prefers-color-scheme 还没来得及生效，页面按默认浅色渲染；等媒体查询匹配完成，样式重绘——这个间隙在 iOS 和部分 Android WebView 中尤其明显，用户会看到白→黑（或黑→白）的突兀跳变。
- 用
window.matchMedia('(prefers-color-scheme: dark)')在 JS 初始化阶段立刻读取当前值，并同步设置document.documentElement.setAttribute('data-theme', 'dark') - 所有核心颜色规则必须同时写两套：
[data-theme="dark"] .btn（防闪） +@media (prefers-color-scheme: dark) .btn（保语义） - 不要依赖 JS 后续才挂载主题类——DOM 渲染前就得有对应 class 或属性
CSS变量 fallback 不是可选项，是必填项
很多人在 :root 定义 --bg: #fff，再在 @media 里覆盖，结果深色下某些组件背景仍是白的。根本原因：变量未在作用域内声明，var(--bg) fallback 到 transparent 或初始值，而不是你期望的暗色。
- 所有主题变量必须在各自媒体查询块内完整声明，比如：
@media (prefers-color-scheme: dark) { :root { --bg: #1a1a1a; --text: #eee; } } - 所有使用变量的地方加默认值：
background: var(--bg, #ffffff)，防止未定义时样式断裂 - 避免在
:root外层统一赋初值再覆盖——媒体查询内的变量不会“回写”，继承链会断
第三方组件（如 Ant Design、Vant）怎么不被你的 dark 规则吞掉
这些库通常靠 JS 注入 .dark 类或动态改 :root 变量，和你的 @media 规则容易打架：要么你的 CSS 被库 reset 掉，要么库的主题开关失效。
立即学习“前端免费学习笔记（深入）”；
- 覆盖时必须提高选择器优先级，例如用
html[data-theme="dark"] .van-button而不是简单写.van-button - 禁用
!important——它会切断变量链，导致后续 JS 主题切换（比如用户点按钮切回浅色）完全失效 - 检查库文档是否提供
theme-changed事件，必要时监听并手动同步data-theme属性
最易忽略的一点：移动端 WebView（尤其是 iOS WKWebView 和旧版 Android WebView）对 prefers-color-scheme 的支持不稳定，可能首次加载就返回 false，且不响应系统切换事件。上线前务必在真机上用 WebDebugX 注入 matchMedia 检测逻辑，不能只信桌面 Chrome DevTools。
