直接用@media (prefers-color-scheme: dark)不可靠，必须搭配CSS变量、JS初始化和属性选择器协同；因其执行时机晚致首屏闪屏，且不支持手动切换、旧浏览器兼容及no-preference场景。
直接用 @media (prefers-color-scheme: dark) 是最可靠的基础，但只靠它无法覆盖手动切换、浏览器不支持、系统未设偏好等真实场景——必须搭配 CSS 变量 + JS 初始化 + 属性选择器三者协同。
为什么 @media (prefers-color-scheme: dark) 单独用会闪屏或失效
浏览器解析 CSSOM 时，@media (prefers-color-scheme: dark) 的值尚未就绪，页面先按默认（通常是亮色）渲染一次，等媒体查询生效后再重绘。iOS Safari 和部分 Android WebView 尤其明显。
- 这不是 CSS 写错了，是执行时机问题
- 旧版 Safari（12.0）、微信内置浏览器、某些 Electron 内核根本不识别该媒体特性
- 用户可能系统设浅色，但偏爱网页深色；或系统没配偏好（
no-preference），此时媒体查询不触发
必须在 :root 中初始化变量，并在媒体查询内完整覆盖
CSS 变量本身不响应媒体查询变化，--bg: #fff 不会在暗色环境下自动变成 #121212。必须把两套定义都写全，且顺序不能错：
:root {
--bg: #ffffff;
--text: #333333;
}
@media (prefers-color-scheme: dark) {
:root {
--bg: #121212;
--text: #e0e0e0;
}
}
- 所有使用处必须加 fallback：
background: var(--bg, #ffffff)，否则变量未定义时样式崩塌 - 别把变量定义在组件选择器里（如
.card { --bg: #fff; }），否则媒体查询无法覆盖 - 避免嵌套过深的 fallback：
var(--a, var(--b, #000))在低端设备上可能延迟计算
第三方组件库（Ant Design / MUI / Chakra）为何颜色错乱
这些库通常靠 JS 注入 class 或修改 :root 变量来切主题，和你的 @media 规则直接冲突。常见表现是：系统切暗色时库没反应，或手动点按钮后颜色错乱。
立即学习“前端免费学习笔记（深入）”；
- 统一入口：改用
[data-theme="dark"] .ant-btn这类更具体的选择器覆盖关键样式 - 不要对
:root直接写!important，否则 JS 后续更新变量会失效 - 必要时在外层加 wrapper，并用
[data-theme="dark"] > .wrapper提升优先级 - 检查文档是否要求额外引入深色主题 CSS 文件（如 Chakra UI 的
css-reset补丁）
color-scheme: light dark 是做什么的，能不能省略
它只告诉浏览器“我支持双模式”，从而让原生控件（<input>、<select>、滚动条、canvas 边框）自动适配系统色。不加的话，这些元素在暗色系统下仍显示亮色边框或白底。
- 它不会影响你写的任何 CSS 规则，也不触发
@media (prefers-color-scheme: dark) - 它是补充项，不是替代项；必须和媒体查询共存
- 最容易被忽略的是 fallback 处理：变量没定义、浏览器不支持媒体查询、用户禁用了系统偏好——这三类情况都会让
var(--bg)返回空值，最终依赖 fallback 值撑住界面
