使用@media (prefers-color-scheme: dark)易闪屏、漏覆盖、第三方组件失效，根源在于执行时机不当与css变量作用域缺失；需js同步读取matchmedia、添加data-theme类，css变量须在媒体查询内完整重定义并配fallback，统一控制第三方库主题，且必须声明color-scheme。
直接用 @media (prefers-color-scheme: dark) 写样式大概率会闪屏、漏覆盖、第三方组件失效——这不是你 CSS 写得不够多，而是没抓住执行时机和变量作用域这两个关键点。
为什么 @media (prefers-color-scheme: dark) 一写就闪屏
浏览器解析 CSSOM 时，@media (prefers-color-scheme: dark) 还没拿到系统偏好值，页面先按亮色渲染一次，等媒体查询生效再重绘。iOS Safari 和部分 Android WebView 尤其明显。
- 必须用 JS 在首屏前同步读取：
window.matchMedia('(prefers-color-scheme: dark)').matches - 立即给
加data-theme="dark"类（不是 class="dark"，除非 Tailwind 显式配置） - 服务端渲染（如 Next.js）要包裹
if (typeof window !== 'undefined')，否则 SSR 阶段报错
--color-bg 这类 CSS 变量在暗色下不生效的真正原因
CSS 变量本身不响应媒体查询。:root { --bg: #fff } 不会在暗色环境下自动变值，必须把整套定义放进媒体查询里，且 fallback 不可省略。
- 基础定义必须存在：
:root { --bg: #ffffff; --text: #333333; } - 覆盖定义必须完整：
@media (prefers-color-scheme: dark) { :root { --bg: #121212; --text: #e0e0e0; } } - 所有使用处加 fallback：
background: var(--bg, #ffffff);—— 否则变量未定义时直接崩样式 - 别把变量全堆在
:root；组件级变量应就近定义，比如.card { --card-bg: var(--bg); }，再在媒体查询里重置它
第三方 UI 库（Ant Design / MUI / Chakra）在暗色下颜色错乱
这些库通常靠 JS 注入 class 或修改 :root 变量来切主题，和你的 @media 规则直接冲突。常见表现是：系统切暗色，库组件颜色不变；或手动切换后颜色错乱。
- 统一入口：用
[data-theme="dark"] .ant-btn这类更具体的选择器覆盖关键样式，避免直接对:root加!important - 检查库文档是否要求额外引入深色 CSS 文件（如 Chakra 的
@chakra-ui/react深色补丁） - 禁用库的自动检测（如
colorModeManager），改由你控制data-theme状态 - 自定义内容（如
.stat-card）必须单独适配，库不会管你的非标准组件
color-scheme: light dark 是不是可有可无？
不是。它不触发 @media，也不改变你写的任何 CSS，但它决定原生控件的渲染逻辑——<input> 边框、<select></select> 下拉箭头、滚动条、canvas 默认边框等，在暗色系统下仍显示亮色，就是缺了它。
- 必须显式声明：
:root { color-scheme: light dark; }或<meta name="color-scheme" content="light dark"> - 声明位置很关键：如果是 CSS-in-JS（如 Emotion），
<meta>必须静态注入 HTML，动态插入无效 - 它只是“告诉浏览器我支持双模式”，不是暗色实现方案本身
最容易被忽略的是 fallback 处理：变量未定义、浏览器不支持媒体查询、用户禁用了系统偏好——这三类情况都会让 var(--bg) 返回空值，最终依赖 fallback 值撑住。别信肉眼判断对比度，用 Chrome DevTools 的「Accessibility」面板实测每个文本元素。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
