应使用 js 提前读取 matchmedia 并设置 data-theme 类避免闪屏；css 变量需在媒体查询内完整定义两套值并加 fallback；第三方库需用 [data-theme="dark"] 隔离覆盖；color-scheme 仅辅助原生控件适配，非暗色模式实现方案。
为什么直接写 @media (prefers-color-scheme: dark) 会闪屏
浏览器构建 CSSOM 时，@media (prefers-color-scheme: dark) 还没拿到系统偏好值，页面先按默认（通常是亮色）渲染一次，等媒体查询生效后再重绘——iOS Safari 和部分 Android WebView 尤其明显。这不是 CSS 写错了，而是执行时机问题。
必须用 JS 提前读取并同步设置：matchMedia('(prefers-color-scheme: dark)').matches，然后给 加 data-theme="dark" 类。这样首屏就能按目标主题渲染，避免视觉跳变。
如何让 CSS 变量在暗色模式下真正生效
CSS 变量本身不响应媒体查询，--bg: #fff 不会在暗色环境下自动变成 #121212。必须把变量定义放进媒体查询里，且确保两套都完整：
-
:root { --bg: #ffffff; --text: #333333; }—— 默认值，必须存在 -
@media (prefers-color-scheme: dark) { :root { --bg: #121212; --text: #e0e0e0; } }—— 覆盖定义，不是“修改” - 所有使用处加 fallback：
background: var(--bg, #ffffff);，防止变量未定义时样式崩塌
第三方 UI 库的样式为什么总被覆盖或失效
Ant Design、MUI 等库通常靠 JS 注入 ant-design-dark 或修改 :root 变量来切主题，和你的 @media 规则直接冲突。常见表现是：系统切暗色时库没反应，或手动点切换按钮后颜色错乱。
解决办法是统一入口，用属性选择器隔离：
- 删掉库自带的暗色 class 注入逻辑（或禁用）
- 改用
[data-theme="dark"] .ant-btn这类更具体的选择器覆盖关键样式 - 避免对
:root直接写!important，否则 JS 后续更新变量会失效 - 必要时在库组件外层加 wrapper，并用
[data-theme="dark"] > .wrapper提升优先级
要不要加 color-scheme: light dark
要，但别指望它“实现”暗色模式。它的作用很窄：告诉浏览器你支持双模式，从而让原生表单控件（<input>、<select></select>）、滚动条、canvas 边框等自动适配系统色。不加的话，这些元素在暗色系统下仍显示亮色边框或白底。
但它不会影响你写的任何 CSS 规则，也不触发 @media (prefers-color-scheme: dark)。所以它是补充项，不是替代项。
最容易被忽略的是 fallback 处理：变量没定义、浏览器不支持媒体查询、用户禁用了系统偏好——这三类情况都会让 var(--bg) 返回空值，最终依赖 fallback 值撑住界面。别省略那个逗号后面的默认色。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
