prefers-color-scheme 无效主因是系统未启用深色模式、file://下Safari禁用该查询、CSS未加载或被覆盖，以及缺失默认浅色样式导致文字在黑背景上不可见；需正确使用 window.matchMedia 并监听 change 事件，优先级上 localStorage 手动设置应高于系统偏好，且所有颜色须通过 CSS 变量统一管理。
prefers-color-scheme 为什么写了却没反应
不是语法错，而是环境或结构卡住了。系统根本没开深色模式，file:// 协议下 Safari 直接禁用该查询，Chrome 可能降级处理；CSS 文件压根没加载成功，或者规则被其他样式覆盖而灰掉（DevTools Styles 面板里看是否 disabled）；更常见的是——只写了 @media (prefers-color-scheme: dark)，但没配默认浅色样式，导致深色系统下 body 沿用浏览器默认白底黑字，你改了 color 却没改 background，结果文字直接糊在黑背景上。
window.matchMedia('(prefers-color-scheme: dark)') 怎么安全读取和监听
别拼错成 prefers-dark-mode 或 prefers-dark-scheme——这些根本不存在。正确写法只有：window.matchMedia('(prefers-color-scheme: dark)').matches，它返回布尔值，不是 Promise，也不是事件对象。
- 监听系统切换必须显式绑定
change事件：window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', handler) - Safari 14+、Chrome 87+、Firefox 96+ 才稳定支持
change，旧版只能 reload 或轮询 - 页面刚加载时
matches值可能被后续 JS 或localStorage覆盖，别当成“最终状态”直接用
data-theme 和 localStorage 怎么协同避免冲突
用户手动点开关的优先级必须高于系统偏好，否则用户切了暗色，系统一调回亮色，页面就自动翻回去——体验崩坏。关键在于初始化顺序和存储逻辑：
- 先查
localStorage.getItem('theme')：有值就用它（"dark"或"light"），没值才查window.matchMedia('(prefers-color-scheme: dark)').matches -
localStorage.setItem('theme', 'dark')存字符串，别存布尔或 JSON；读取时做兜底：saved || 'light'，否则data-theme="null"会让 CSS 规则失效 - 切换函数里同步更新
document.documentElement.dataset.theme和localStorage，不操作body.classList——data-theme更语义、更利于 Shadow DOM 和 scoped 样式隔离
哪些元素最容易在深色下糊成一片
prefers-color-scheme 不会自动翻转任何自定义内容，只触发 CSS 规则。这些地方必须手动适配：
立即学习“前端免费学习笔记（深入）”；
-
<input type="range">、<select>等原生控件：加color-scheme: light dark到:root，再用@media显式设background、border、color -
<img>和内联<svg>：别指望“自动变暗”，图标发灰就加filter: brightness(0.8)或准备双版本；SVG 用currentColor配合 CSS 变量更可控 - 阴影和边框：
box-shadow: 0 2px 4px rgba(0,0,0,0.8)在深色背景下太重，换成rgba(0,0,0,0.2)；border: 1px solid #ccc在黑底上几乎看不见，得改成#444或变量
最易忽略的是：所有颜色值必须通过 var(--text)、var(--bg) 这类变量统一管理，否则切主题时只改了 :root 变量，按钮、卡片、表单等组件样式没跟着变，等于白干。
