@media (prefers-color-scheme: dark) 未生效主因是规则被覆盖或未正确触发：浅色变量未在 :root 先声明、深色规则位置靠前、嵌套媒体查询被旧版 Safari 忽略；须确保 :root 默认值先行、深色规则后置、变量名完全一致且全覆盖，并添加 color-scheme 声明适配原生控件。
@media (prefers-color-scheme: dark) 不是“写了就生效”，而是极易被覆盖或跳过——关键在顺序、变量声明和配套声明三处。
为什么 @media (prefers-color-scheme: dark) 没反应
不是浏览器不支持，而是它根本没执行到。常见原因包括：
-
@media规则写在:root默认变量声明之前，旧版 Safari 直接忽略整块媒体查询 - 浅色变量没在
:root里先定义（比如漏了--border-color），导致深色模式下var(--border-color)fallback 成transparent或浏览器默认灰边 - 把媒体查询嵌套在其他条件里，例如
@media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }，Safari 12–15 会静默丢弃 - 页面已加载后切换系统主题，该媒体查询不会重触发（它只在初始渲染时读取一次）
:root 变量必须先声明默认值再覆盖
所有变量都得在 :root 顶层一次性声明，不能靠媒体查询“新增”变量。
:root {
--bg-primary: #ffffff;
--text-primary: #333333;
--border-color: #e0e0e0;
--shadow-sm: 0 1px 2px rgba(0,0,0,0.05);
}
@media (prefers-color-scheme: dark) {
:root {
--bg-primary: #121212;
--text-primary: #e0e0e0;
--border-color: #333333;
--shadow-sm: 0 1px 2px rgba(0,0,0,0.3);
}
}
- 漏掉任意一个变量，对应组件就会失色（如按钮无阴影、输入框无边框）
- 别用
--dark-bg这类仅深色模式存在的变量，浅色模式下var(--dark-bg)无法解析 - 变量名大小写、拼写必须完全一致，CSS 自定义属性区分大小写
color-scheme 和 <meta name="color-scheme"> 缺一不可
只加 color-scheme: light dark 到 :root，<input>、<select>、滚动条依然卡在浅色外观。
立即学习“前端免费学习笔记（深入）”；
- 必须在
<head>里加<meta name="color-scheme" content="light dark">，这是触发 UA 控件自动适配的硬性开关 -
color-scheme本身不改你的background-color或color，它只影响表单边框、<progress>轨道、::-webkit-scrollbar等原生控件 - 系统语义色（如
Canvas、CanvasText）比硬编码十六进制更稳，但它们不支持 alpha；需要半透时得用color-mix(in srgb, CanvasText 70%, transparent)或 fallback 变量
手动切换与系统偏好共存的关键点
用户点击“深色模式开关”时，JS 只应操作 class，不能直接改 style.setProperty()。
- 推荐结构：
<html class="dark">+.dark :root { ... }，且该规则需放在@media (prefers-color-scheme: dark)之后，确保优先级更高 - 初始化 JS 必须早于首屏渲染（如放在
<head>的<script>里），并从localStorage读取上次用户选择 -
matchMedia('(prefers-color-scheme: dark)')可监听系统变化，但仅用于同步状态（比如更新按钮图标），不要用它来接管样式逻辑
最容易被忽略的是：所有 CSS 变量使用处都必须带 fallback，比如 background-color: var(--bg-primary, #ffffff); —— 否则变量未定义时，部分浏览器会回退成透明，页面直接“消失”。
