最常见原因是CSS加载顺序和规则位置错误，需将@media(prefers-color-scheme:dark)置于所有默认样式之后、避免嵌套、在:root中先定义浅色变量并完整重写、添加color-scheme:light dark启用原生控件适配，且SSR需内联关键样式并同步data-color-scheme属性防闪动。
为什么写了 @media (prefers-color-scheme: dark) 却没生效
最常见原因是 CSS 加载顺序和规则位置不对。浏览器按声明顺序应用样式，@media 规则本身不提升优先级，只靠后置覆盖。如果深色规则写在亮色规则前面，或者被包裹在其他媒体查询里（比如 @media (min-width: 768px) { @media (prefers-color-scheme: dark) { ... } }），旧版 Safari 会直接忽略。
- 确保所有基础变量先在顶层
:root中定义，例如--bg: #fff;、--text: #333; -
@media (prefers-color-scheme: dark)块必须放在这些默认定义之后 - 别嵌套它——单独、顶层、无包裹
- 用 DevTools 的 Styles 面板检查：模拟系统主题切换后，目标规则是否被划掉（未匹配）；若没划掉但颜色没变，大概率是 selector 优先级不够，或被
!important/ inline style 压制
怎么用 :root 变量安全管理主题色
CSS 自定义属性是静态求值的，浏览器不会“回溯”已计算的 var() 值。变量重定义必须发生在匹配的媒体查询内部，且依赖声明顺序。
- 把所有基础变量写在顶层
:root，保证不匹配时有 fallback（如系统设为no-preference或浏览器不支持） - 在
@media (prefers-color-scheme: dark)内完整重写需要变更的变量，名称必须完全一致 - 避免只改部分变量（比如只改
--bg却漏掉--border），否则组件可能混用明暗色值导致对比度崩坏 - 别在媒体查询里对同一变量反复赋值（如先设
--bg: #1a1a1a，又在子选择器里再设），CSS 不支持变量“局部作用域”
如何防止 SSR 页面首次加载白屏闪动
服务端无法读取客户端系统偏好，Next.js/Nuxt 等框架首屏必然按默认主题输出 HTML，等 JS 执行 window.matchMedia 后才补上深色类——这个间隙就是闪动来源。
- 在
标签上同步注入data-color-scheme属性（服务端根据 User-Agent 或客户端 hydration 逻辑注入） - 让关键 CSS（尤其是
:root变量）通过<style></style>标签内联，避免外链 CSS 加载延迟导致样式错乱 - 首屏关键样式里，把亮色作为默认，不要硬编码
dark或留空主题（如theme-pending类） - 如果用 CSS-in-JS（如 Emotion），确认其版本支持
prefers-color-scheme透传；旧版会剥离该媒体查询
要不要加 color-scheme: light dark
要，而且建议加在 :root 上。它不控制你的文字或背景，但能告诉浏览器：你的页面支持双模式，从而自动调整原生控件（输入框、按钮、滚动条、复选框等）的配色，避免深色背景下弹出刺眼的白色表单元素。
立即学习“前端免费学习笔记（深入）”；
- 写法很简单：
:root { color-scheme: light dark; } - 它和
@media (prefers-color-scheme: dark)是互补关系：一个管浏览器控件，一个管你写的样式 - 局部启用也行，比如只给某个卡片加
.card { color-scheme: dark; }，但全局统一更省心 - 主流现代浏览器（Chrome、Firefox、Safari）均已支持，老版本忽略即降级，无风险
localStorage 存的不能是最终主题，而应是“用户覆盖意图”，否则系统关掉深色模式后页面还固执地黑着。 
