@media (prefers-color-scheme: dark) 未生效主因是CSS层叠顺序错误、变量未在:root中双套定义、缺少color-scheme声明或被动态插入/嵌套写法干扰，需顶层先设浅色默认值再用媒体查询整体覆盖，并统一处理表单、SVG、滚动条等非变量元素。
直接用 @media (prefers-color-scheme: dark) 就能响应系统深色偏好，但必须写在 CSS 文件或 <style></style> 块里，且所有颜色变量得在 :root 中明确定义两套——漏一条、顺序错、没加 color-scheme 声明，都会导致“开了深色模式却还是白底黑字”。
为什么写了 @media (prefers-color-scheme: dark) 却没反应
不是媒体查询失效，而是它被覆盖、忽略或根本没加载成功。常见原因包括：
- 深色规则写在浅色样式之前，被后续无条件的
:root定义覆盖（CSS 按声明顺序生效，不按媒体类型提升优先级） - 把媒体查询嵌套在其他条件里，比如
@media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }，旧版 Safari 直接跳过 - CSS 是通过 JS 动态插入的
<style></style>标签，部分浏览器不触发匹配 -
:root里只定义了暗色变量，没初始化浅色默认值，系统设为 light 或不支持时，变量读不到值，回退到浏览器默认（常是白底黑字）
: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 这些“隐形元素”怎么一起切
只改自定义变量对它们完全无效。它们依赖系统语义色或 UA 样式，需额外处理：
立即学习“前端免费学习笔记（深入）”；
- 必须加
html { color-scheme: light dark; }，否则 iOS Safari 和某些安卓 WebView 会强制渲染为浅色表单控件 - 原生控件（
<input>、<button></button>、<select></select>）的颜色由 UA 控制，color-scheme启用后，它们会自动用Canvas、CanvasText等系统色，无需手动写死 - SVG 的
fill和stroke不继承 CSS 变量，得显式写成fill: var(--icon-color);并确保该变量已在:root两套中定义 - 滚动条颜色不能靠变量，得单独用
::-webkit-scrollbar配合媒体查询重写，或直接用scrollbar-color: auto;让浏览器接管
手动切换按钮和系统偏好怎么共存不打架
纯媒体查询是被动的，用户点按钮后刷新就回退；但若 JS 强行加 class="dark" 又和媒体查询逻辑冲突。稳妥解法是分层控制：
- 用
data-theme="dark"作为最高优先级信号，JS 负责读写localStorage并设置该属性 - CSS 中把手动主题规则写在媒体查询之前（利用层叠顺序：后声明的 class 规则 > 媒体查询规则）
- 媒体查询只作 fallback：当
data-theme为空时，才按系统偏好生效 - 监听
window.matchMedia('(prefers-color-scheme: dark)')的change事件，但仅在用户从未手动选择时才响应，避免覆盖用户意图
最易被忽略的是：深色模式下纯黑 #000 和纯白 #fff 实际体验很差，尤其小字号文字易发虚、高对比刺眼；系统用的多是 #121212～#1e1e1e 和 #e0e0e0～#f0f0f0，这些值得手写进变量，不能指望媒体查询自动“智能变暗”。
