直接写@media (prefers-color-scheme: dark)可检测系统暗黑模式，但常因系统未开启、file://协议限制、CSS加载错误、缺失默认亮色样式或JS监听不当而失效；需结合localStorage、data-theme属性及内联脚本避免闪屏并支持手动切换。
直接写 @media (prefers-color-scheme: dark) 就能检测，但只靠它不能实现可靠暗黑模式——它不响应用户手动切换，也不保证首屏不闪屏。
为什么 @media (prefers-color-scheme: dark) 常常“不生效”
失效通常不是语法错，而是环境或结构问题：
- 系统根本没开深色模式 → 先去 macOS「系统设置」、Windows「设置 → 个性化 → 颜色」或 iOS「设置 → 显示与亮度」确认
- 用
file://协议双击打开 HTML → Safari 会禁用该媒体查询，Chrome 可能降级；改用python3 -m http.server启服务再测 - CSS 文件未加载或有语法错误 → 打开 DevTools 的「Styles」面板，看对应规则是否灰掉（disabled）
- 只写了暗色规则，没写默认亮色样式 → 深色系统下所有未被覆盖的元素沿用浏览器默认（比如
body白底黑字），一旦你只改了color没改background，就变成黑字配黑底
window.matchMedia('(prefers-color-scheme: dark)') 怎么安全读取和监听
JS 中不能拼错成 prefers-dark-mode 或漏括号。正确用法是：
-
window.matchMedia('(prefers-color-scheme: dark)').matches返回布尔值，表示当前系统是否处于暗色模式 - 必须显式绑定
addEventListener('change', handler)才能响应系统切换；onchange不起作用 - Safari 14+、Chrome 87+、Firefox 96+ 才稳定支持
change事件；旧版只能 reload 或轮询 - 别在页面刚加载时就假设
matches是最终值——它可能被后续 JS 或localStorage覆盖
如何避免首屏闪烁和主题丢失
最常被忽略的性能陷阱：CSS 变量依赖 JS 注入，或主题 class 晚于 HTML 渲染添加，导致首屏闪白或闪黑。
立即学习“前端免费学习笔记（深入）”；
- 把初始判断逻辑放到
<head>的内联<script>中，早于任何样式表和 DOM 渲染 - 避免依赖
DOMContentLoaded—— 此时 HTML 已解析完毕，但样式可能已按默认主题渲染过一帧 - 优先读
localStorage.getItem("theme")，返回null时再 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches；别把null直接赋给dataset.theme（会导致data-theme="null"，CSS 匹配失败） - 每次切换后必须同步调用
localStorage.setItem("theme", "dark")，否则刷新即失效
为什么不能只靠 prefers-color-scheme 实现完整暗黑模式
它只反映系统偏好，不是用户真实意图：
- 很多人开着深色系统，但只想在某个网站用亮色（比如夜间看代码教程，黑底浅灰
<pre>文字糊成一片） - 用户点击「☀️/?」按钮后，必须把选择存到
localStorage，否则刷新就打回原形 -
prefers-color-scheme最适合做「首次访问默认值」，不是最终决策者 - 推荐策略：用
data-theme属性作为唯一可信源，CSS 中写[data-theme="dark"] { }和@media (prefers-color-scheme: dark) [data-theme="auto"] { }
真正难的不是监听系统主题，而是在用户手动切换后，还能平滑过渡、保留偏好、不破坏可访问性（比如不重置 prefers-reduced-motion 设置）。
