根本原因是未处理初始渲染时机、变量作用域和样式优先级三处硬伤：媒体查询异步导致闪屏；:root变量无法被媒体查询动态回写需重置并加fallback；第三方组件需用[data-theme="dark"]强制接管并提升选择器优先级。
只写 @media (prefers-color-scheme: dark) 会闪屏、变量不生效、第三方组件失联——根本不是语法问题，而是没处理初始渲染时机、变量作用域和样式优先级这三处硬伤。
为什么页面加载时总先白一下再变黑
浏览器解析 HTML 和 CSS 是同步的，但系统偏好读取是异步的。prefers-color-scheme 媒体查询生效前，:root 里的变量已按默认值（比如 --bg: #fff）完成首次渲染；等媒体查询匹配上，才触发重绘，造成肉眼可见的闪烁。iOS Safari 和 Android WebView 尤其明显。
- 必须在
<head>中内联轻量 JS，用matchMedia('(prefers-color-scheme: dark)')同步检测，并给<html>添加data-theme="dark"类 - 所有关键样式要同时写两套：
[data-theme="dark"] .card（防闪） +@media (prefers-color-scheme: dark) .card（保语义） - 别依赖 SSR 或服务端判断主题——首屏直出无法预知客户端系统设置
CSS 变量在暗色下为啥还是白的
--bg: #fff 写在顶层 :root，再在 @media 块里改值，看似合理，但变量继承是动态的，而媒体查询块内的声明不会“回写”到根作用域。如果某个组件提前用了 var(--bg)，此时变量还没被媒体查询覆盖，就会 fallback 到初始值或透明。
- 正确做法：在
@media (prefers-color-scheme: dark)内完整重置:root变量，例如：@media (prefers-color-scheme: dark) { :root { --bg: #1a1a1a; --text: #e0e0e0; } } - 所有使用变量的地方必须加 fallback：
background: var(--bg, #ffffff)，防止未定义时样式崩塌 - 避免在
:root外再套其他媒体查询（如@media (max-width: 768px)），旧版 Safari 不识别复合条件
Ant Design / MUI 等组件为啥不跟着变暗
这些库自带暗色开关，但通常靠 JS 注入 class 或修改 :root 变量，和你的 @media 规则冲突——要么库的主题被你覆盖，要么你的样式被库 reset 掉。
立即学习“前端免费学习笔记（深入）”；
- 优先查文档：
MUI v5+支持useMediaQuery('(prefers-color-scheme: dark)')，Ant Design 5.1+有algorithm: theme.darkAlgorithm - 若库不支持，用
[data-theme="dark"]强制接管，例如：[data-theme="dark"] .ant-btn - 注意选择器优先级：库的样式常带多层嵌套，你的覆盖规则至少要比它多一级，比如用
html[data-theme="dark"] .ant-input - 禁用
!important——它会切断变量链，导致后续 JS 主题切换失效
最易忽略的是移动端 WebView 兼容性：iOS WKWebView 和部分 Android WebView 对 prefers-color-scheme 的支持不稳定，首次加载可能直接忽略媒体查询，必须真机测试并保留 data-theme 降级路径。
