必见白屏闪动且原生控件不响应，因渲染时机滞后、CSS变量未在:root显式初始化、缺color-scheme声明及meta标签；须内联JS同步设data-theme、双写[data-theme]与@media规则、所有var()加fallback，并确保color-scheme与meta同时存在。
只写 @media (prefers-color-scheme: dark) 就上线，移动端用户必见白屏闪动，且表单、滚动条、SVG 图标大概率仍为浅色——这不是 CSS 写错了，是渲染时机、变量作用域和 UA 控件适配三处没对齐。
为什么写了 @media (prefers-color-scheme: dark) 却没反应
常见现象：DevTools 里媒体查询规则亮着（未被划掉），但 <input> 还是白底黑字，<select> 边框发亮，滚动条 thumb 没变暗。
- 浏览器首次构建样式时，
prefers-color-scheme还未读取完成，:root中变量已按默认浅色解析并应用；等媒体查询生效，才重绘——iOS Safari 和多数 Android WebView 渲染间隙明显，肉眼可见“白→黑”闪动 -
@media规则必须写在<style>标签或外链 CSS 文件中，不能用document.styleSheets[0].insertRule()动态插入，部分 WebView 静默失败 - 规则若嵌套在其他媒体查询里（如
@media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }），Safari 12.1 及更早版本直接跳过整块 - 漏定义浅色默认值：比如
:root { --bg: #fff; }没写，深色媒体查询里再设--bg: #121212，浅色模式下var(--bg)fallback 到透明或浏览器默认值，页面局部空白或错色
怎样避免首屏白屏闪动
核心是让 DOM 在首次绘制前就带主题语义，不能等 CSSOM 构建完再靠媒体查询“补救”。
- 在
<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（保系统切换响应） - CSS 变量必须全部定义在
:root，不能写在.dark或body下——否则<input>、伪元素、Shadow DOM 内部读不到，直接 fallback - 每个
var()必须带 fallback：background: var(--bg, #ffffff);，但 fallback 值不随主题变，所以它只是兜底，不是主题逻辑主体
怎样让表单、滚动条、SVG 自动变暗
@media 只管你自己写的样式，<input>、<select>、::-webkit-scrollbar、<svg> 的颜色默认不读 CSS 变量，得靠浏览器 UA 主动适配。
立即学习“前端免费学习笔记（深入）”；
- 必须在
<html>或:root上加color-scheme: light dark;——这是触发 UA 自动切换的硬性开关，仅靠 CSS 层声明无法替代 - 必须在
<head>加<meta name="color-scheme" content="light dark">，尤其 iOS Safari 和部分 WebView 中，缺这个标签color-scheme声明会完全失效 - 滚动条需单独写伪元素：
::-webkit-scrollbar-thumb { background-color: var(--scroll-thumb, CanvasText); }，不能省略，也不能只靠color-scheme - 内联 SVG 图标要用
fill: currentColor或fill: var(--icon-fill)，filter: invert(1)会破坏语义、高对比度下不可读
第三方组件（Ant Design/Vant/NutUI）为啥不跟着变暗
这些库通常靠 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，能原生对接 - 别混用入口：如果项目已用
data-theme控制主题，就别再让第三方库也接管:root变量，统一由客户端 JS 初始化和监听
最容易被忽略的是：所有使用 var(--xxx) 的地方，都必须确保该变量已在 :root 显式初始化；而所有原生控件（表单、滚动条、Canvas 文本）是否变暗，不取决于你写了多少 CSS，只取决于 <meta name="color-scheme"> 是否存在、color-scheme 是否声明、以及它们是否出现在渲染前的 HTML 中。
