@media (prefers-color-scheme: dark) 不生效的根本原因是：变量未在 :root 显式初始化、媒体查询未置于默认样式之后、原生控件缺少 color-scheme 和 <meta> 声明，三者缺一即导致白屏、闪动或颜色错乱。
只写 @media (prefers-color-scheme: dark) 不会生效——变量没初始化、顺序错、原生控件不响应，三者缺一都会导致白屏、闪动或颜色错乱。
为什么 @media (prefers-color-scheme: dark) 写了也没用
不是语法错，而是浏览器渲染链断在了前几步：CSS 加载时，:root 里没定义 --bg、--text 等基础变量，深色媒体查询一触发，var(--bg) 就 fallback 到浏览器默认值（比如 Canvas 白底），整个页面瞬间“变亮”；更常见的是深色规则写在浅色样式之前，被后面无条件声明直接覆盖；还有就是 <input>、滚动条这些原生元素压根不看你写的 CSS 变量，只认 color-scheme 和 <meta>。
-
@media规则不提升优先级，只靠后置覆盖——必须放在所有默认样式之后 - 漏定义任一变量（如
--border-color），深色模式下该属性就失效，不是“保持浅色”，而是退成浏览器默认灰/白 - 嵌套写法如
@media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }在 Safari 12.1 之前完全被忽略
必须在 :root 里显式初始化所有变量
所有主题变量得在顶层一次性定义好浅色默认值，不能靠 fallback（如 var(--bg, #fff)）撑场子——fallback 是兜底，不是主题逻辑。系统切到深色时，它不会自动更新，只会卡死在 #fff。
- 写成：
:root { --bg: #ffffff; --text: #333333; --border: #e0e0e0; } - 别漏掉边框、阴影、图标 fill、SVG 颜色等高频变量
- 如果项目已用
body.dark类控制主题，就把变量定义挪进该 class 里，避免和媒体查询冲突
原生控件必须靠 color-scheme + <meta> 启动
color-scheme: light dark 这个声明本身不改你的背景或文字颜色，它只告诉浏览器：“我支持双主题，请自动调整 <input>、<progress>、::-webkit-scrollbar、Canvas 文本等 UA 控件。”但没 <meta name="color-scheme" content="light dark">，iOS Safari 和多数 WebView 直接无视这个声明。
立即学习“前端免费学习笔记（深入）”；
-
<meta>必须放在<head>最前面，早于任何 CSS 或 JS -
color-scheme推荐加在:root或html上，不要只加在某个组件里 - 自定义滚动条、
<svg>图标需单独处理：fill: var(--icon-fill)或fill: currentColor，不能靠color-scheme自动翻转
防首屏闪动的关键是内联 + 双路径
SSR 或静态页首屏必然闪——服务端不知道客户端系统偏好，只能直出浅色。等 JS 执行 window.matchMedia 再改 DOM，用户肉眼可见“白→黑”一跳。唯一可靠方案是：HTML 内联轻量 JS 检测并打标记，CSS 同时写两套规则。
- 在
<head>内联 JS：const mql = window.matchMedia('(prefers-color-scheme: dark)'); document.documentElement.setAttribute('data-theme', mql.matches ? 'dark' : 'light'); - CSS 同时写：
[data-theme="dark"] .card { background: var(--bg); }（防闪） +@media (prefers-color-scheme: dark) .card { background: var(--bg); }（保语义） - 别用
localStorage缓存系统偏好——用户改系统设置后，缓存就过期，页面不同步
最易被忽略的点是：所有用了 var() 的地方，都得确认对应变量已在 :root 初始化；所有原生控件，都得检查 <meta> 和 color-scheme 是否到位；所有 CSS 变量名，在媒体查询里必须和 :root 定义时**严格一致**，多一个空格、少一个连字符都会断链。
