必须在<head>中内联JS检测prefers-color-scheme并设置data-theme属性，同时CSS变量需定义在@media内部且使用fallback，才能避免白屏闪动和样式失效。
只写 @media (prefers-color-scheme: dark) 就上线，90% 的移动端用户会看到白屏闪一下再变黑——这不是 bug，是浏览器渲染机制决定的必然现象。
为什么 iOS Safari 加载时总先白一下再变黑
浏览器首次构建 CSSOM 时，prefers-color-scheme 还没完成系统偏好读取，:root 里的变量（比如 --bg: #fff）已按默认浅色解析并应用；等媒体查询匹配完成，样式重绘，视觉上就是一次“闪屏”。iOS Safari 和多数 Android WebView 尤其明显。
- 必须在
<head>中内联轻量 JS：window.matchMedia('(prefers-color-scheme: dark)').matches立即检测，并同步设置document.documentElement.setAttribute('data-theme', 'dark') - 所有关键样式规则要写两套：
[data-theme="dark"] .card（防首屏闪） +@media (prefers-color-scheme: dark) .card（保语义和后续系统切换响应） - 别依赖 SSR 或服务端判断主题——首屏 HTML 无法预知客户端系统设置，纯靠客户端 JS 同步才是唯一可靠路径
CSS 变量在深色下为啥还是白的
--bg: #fff 写在顶层 :root，再用 @media 覆盖，看似合理，但变量继承不回写：组件若在媒体查询生效前就用了 var(--bg)，就会 fallback 到未定义状态（常是透明或浏览器默认），而不是你期望的暗色值。
- 变量定义必须放在媒体查询内部：
@media (prefers-color-scheme: dark) { :root { --bg: #1a1a1a; --text: #eee; } } - 所有使用处强制加 fallback：
background: var(--bg, #ffffff)，不能省略第二个参数 - 不要在
:root外层再套其他媒体查询（如@media (max-width: 768px)），旧版 Safari 不识别复合条件，整块规则会被跳过
Ant Design、Vant 等第三方组件为啥不跟着变暗
这些库通常靠 JS 注入 .dark 类或动态改 :root 变量，和你的 @media 规则天然冲突——要么你的样式被库 reset，要么库的主题开关失效。
立即学习“前端免费学习笔记（深入）”；
- 覆盖必须提高选择器优先级：
html[data-theme="dark"] .ant-btn比.ant-btn多两级，才能压过库的嵌套样式 - 禁用
!important：它会切断变量链，导致后续用户手动切回浅色时完全失效 - 优先查文档：MUI v5+ 支持
useMediaQuery('(prefers-color-scheme: dark)')，Ant Design 5.1+ 有algorithm: theme.darkAlgorithm，能原生对接
还有个真机里才暴露的硬伤：WebView 兼容性
iOS WKWebView 和部分 Android WebView 对 prefers-color-scheme 的支持不稳定——首次加载可能直接忽略媒体查询，或延迟数秒才触发。这不是你代码的问题，是运行环境限制。
- 必须真机测试，模拟器不可信；尤其关注微信内置浏览器、QQ 浏览器、钉钉 WebView
-
color-scheme: light dark要加在:root或html上，它不控制业务样式，但能影响表单控件、滚动条、原生按钮等“隐形元素”的配色 - 如果项目必须支持老 WebView，得准备降级方案：比如监听
matchMedia的change事件，手动触发 class 切换 + 变量重设，而非只靠 CSS 媒体查询
最易被忽略的是：系统偏好变更后，页面不会自动重排，但用户可能正在操作表单或滚动——这时候变量已更新，但 DOM 树没重绘，某些元素颜色会卡在旧状态。这不是 CSS 能解决的，得靠 JS 主动触发小范围重绘或强制 class 切换来兜底。
