prefers-color-scheme 媒体查询本身不切换模式，仅响应系统设置；真正起效的是通过:root变量配合赋值，漏默认值、变量名不一致或缺失color-scheme声明都会导致深色模式失效。
prefers-color-scheme 媒体查询本身不“切换”模式，它只响应系统设置；真正起作用的是你如何用 :root 变量配合它赋值——漏掉默认值、变量名不一致、color-scheme 缺失，都会导致“开了深色模式但页面还是白的”。
为什么写了 @media (prefers-color-scheme: dark) 却没反应
不是媒体查询失效，而是它被覆盖或根本没生效。常见原因包括：
-
:root里没先定义浅色默认值，比如只写了--bg: #121212，系统设为 light 时变量为空，回退到浏览器默认（白底黑字） - 深色规则写在浅色样式之后，但又被后面无条件的
:root声明覆盖（CSS 按顺序匹配，媒体查询不自动提权） -
@media块被嵌套在其他查询里，例如@media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }，旧版 Safari 直接跳过 -
color-scheme: light dark没加在html上，导致<input>、滚动条等原生控件卡在浅色状态
:root 变量必须怎么定义才不会失效
变量不是全局常量，它的值取决于声明位置和是否被后续规则重写。安全做法是：
- 所有主题变量（如
--bg-base、--text-primary）必须在顶层:root中先给浅色默认值 - 再用
@media (prefers-color-scheme: dark) { :root { ... } }整体覆盖，变量名完全一致，不新增、不缩写 - 避免 fallback 写法：
var(--bg-base, #fff)的#fff不随主题变，深色下若--bg-base未定义，就真显示白色 - 别在媒体查询里定义新变量，比如
@media (prefers-color-scheme: dark) { :root { --bg-dark-only: #121212; } }—— 浅色下读不到这个变量，var(--bg-dark-only)会失效
表单、SVG、滚动条这些“隐形元素”怎么一起变色
只改 CSS 变量对它们完全无效，因为它们依赖系统语义色或 UA 样式。必须额外处理：
立即学习“前端免费学习笔记（深入）”；
- 加
html { color-scheme: light dark; }，否则 iOS Safari 和部分安卓 WebView 会强制渲染为浅色表单控件 - 原生控件（
<input>、<button></button>、<select></select>）的颜色由 UA 控制，color-scheme启用后，它们会自动用Canvas、CanvasText等系统色，无需手动写死 - SVG 中的
fill、stroke需显式使用变量，例如fill: var(--text-primary)；不能依赖继承或系统色 - 滚动条颜色需单独写伪元素规则，如
::-webkit-scrollbar-thumb，且值也要用变量
用户手动切换时，color-scheme 还要不要设
要，但它是辅助项，不是主力。你在 加了 class="dark" 后，应该同步更新 color-scheme 值，否则原生控件可能卡在系统旧状态。更稳妥的做法是：
- 用
data-theme属性控制优先级（data-theme="dark">prefers-color-scheme） - JS 初始化时读取
localStorage或window.matchMedia，但后续一切以data-theme为准 - 不要监听
prefers-color-scheme做自动切换——它无法被 JS 模拟，只能作为初始 fallback
最易被忽略的其实是变量作用域和初始化顺序：哪怕只漏一个 --border-subtle，某个分割线就会在深色下消失；哪怕 color-scheme 少写一个 dark，iOS 表单就永远白底黑字。
