@media (prefers-color-scheme: dark) 无效的根本原因在于变量未初始化、层叠顺序错误及原生控件未适配，需在 :root 显式定义默认值、确保媒体查询置于样式末尾、添加 color-scheme 声明并内联关键 CSS 防闪动。
@media (prefers-color-scheme: dark) 能直接响应系统设置，但只写这条规则，90% 的页面会闪动、白屏或颜色错乱——根本问题不在语法，而在变量初始化、层叠顺序和原生控件适配没对齐。
为什么写了 @media (prefers-color-scheme: dark) 却没反应
不是浏览器不支持，而是 CSS 加载和计算时机出了问题。常见现象包括：DevTools 里规则没被划掉（说明匹配成功），但元素颜色仍是浅色；或者深色模式下背景突然变白、文字看不清。
-
@media (prefers-color-scheme: dark)必须写在<style>标签或外链 CSS 文件里，不能用document.styleSheets[0].insertRule()动态插入——部分浏览器静默失败 - 深色规则如果写在浅色
:root定义之前，会被后续无条件声明覆盖（CSS 按顺序生效，媒体查询不提升优先级） -
:root里没预先定义所有变量的浅色默认值，比如漏了--border-color，深色模式下var(--border-color)就 fallback 到浏览器默认值（常是浅灰，和深背景形成低对比） - 嵌套写法如
@media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }在 Safari 12.1 之前完全不生效
如何安全定义主题变量避免闪动和错色
闪动本质是渲染分两步：先按未生效的 :root 默认值画一遍，再等媒体查询重算。iOS Safari 和 Android WebView 尤其明显。
- 所有基础变量必须在顶层
:root显式初始化，以浅色为默认：--bg: #ffffff;、--text: #333333;、--border: #e0e0e0; -
@media (prefers-color-scheme: dark)块必须放在所有默认样式之后，并完整覆盖所有相关变量，名称严格一致，不新增、不缩写 - 每个
var()都加 fallback，例如background: var(--bg, #ffffff);——但注意 fallback 值不会随主题变，所以优先靠初始化兜底，而非依赖 fallback - 别在媒体查询里定义新变量（如
--bg-dark-only），浅色环境下读不到，var(--bg-dark-only)直接失效
怎么让表单、滚动条、SVG 也自动适配
CSS 变量只管你自己写的样式，<input>、<select>、::-webkit-scrollbar、<svg> 的 fill/stroke 默认不读变量，得靠 color-scheme 声明触发 UA 自动切换。
立即学习“前端免费学习笔记（深入）”；
- 在
:root或html上加color-scheme: light dark;，Chrome 85+、Firefox 96+、Safari 15.4+ 会自动用 Canvas/CanvasText 等语义化系统色渲染原生控件 - 自定义滚动条需手动重写：
@media (prefers-color-scheme: dark) { ::-webkit-scrollbar-thumb { background: #444; } } - SVG 图标颜色必须显式绑定变量：
fill: var(--icon-color);，并确保该变量已在:root中双套定义 - 单独写
color-scheme: dark会强制深色，破坏“跟随系统”逻辑，除非你明确禁用用户偏好
服务端渲染（SSR）页面如何防首屏闪动
服务端无法读取客户端系统偏好，Next.js/Nuxt 等框架首屏必然按默认主题直出 HTML，JS 加载后才补深色类——这个间隙就是闪动来源。
- 在
<html>标签上同步注入data-color-scheme属性（服务端用 User-Agent 特征推测 + 客户端 hydration 补正） - 关键 CSS（尤其是
:root变量和@media (prefers-color-scheme: dark)块）必须内联到<head>，避免外链加载延迟 - 如果用 Emotion、Styled Components 等 CSS-in-JS 库，确认版本支持
prefers-color-scheme透传；旧版会剥离该媒体查询，导致服务端与客户端样式不一致 - 别依赖 localStorage 缓存系统偏好——系统设置变了，缓存就成脏数据，且首次访问时 localStorage 还是空的
真正麻烦的不是写对那行 @media (prefers-color-scheme: dark)，而是它背后那一整套变量生命周期管理、层叠顺序控制和原生控件协同机制。漏掉任意一环，都可能让深色模式在某个设备、某次刷新、某种 SSR 场景下彻底失效。
