仅靠@media (prefers-color-scheme: dark)无法实现可靠暗黑模式，因其不保存用户选择、不防首屏闪屏、不响应手动切换；失效主因是file://协议限制、css加载错误、缺失默认亮色样式、媒体查询位置靠前被覆盖，或旧版webview不支持。
仅靠 @media (prefers-color-scheme: dark) 无法实现可靠暗黑模式——它不保存用户选择，也不防首屏闪屏，更不响应手动切换。
为什么 @media (prefers-color-scheme: dark) 常常“看起来没生效”
失效几乎从不因为语法写错（比如误写成 = dark），而是环境或结构问题：
- 用
file://协议直接双击打开 HTML 文件 → Safari 会禁用该查询，Chrome 可能降级；改用python3 -m http.server启本地服务再测 - CSS 文件加载失败或含语法错误 → 打开 DevTools 的「Styles」面板，看对应规则是否灰掉（disabled）
- 只写了暗色规则，没写默认亮色样式 → 系统是暗色时，未被覆盖的元素沿用浏览器默认（比如
body白底黑字），结果你只改了color没改background，文字就糊在黑背景上 - 媒体查询写在
@import后面且没加@layer控制顺序 → 被前面更宽泛的规则覆盖
如何让 prefers-color-scheme 和用户手动切换共存
系统偏好只是初始信号，不是最终决定；用户点一下 ☀️/? 按钮，就得立刻生效并记住。关键在三点协同：
- 用
data-theme属性作为唯一可信源：设在上，值为"light"、"dark"或"auto" - 初始化时优先读
localStorage.getItem("theme")；返回null时再 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 每次切换后必须同步调用
localStorage.setItem("theme", "dark")，否则刷新即丢失 - CSS 中同时写：
[data-theme="dark"] { }和@media (prefers-color-scheme: dark) [data-theme="auto"] { }
怎么避免首屏闪烁和主题错乱
闪屏本质是 CSS 变量或 class 注入晚于首次渲染。最稳做法是把判断逻辑塞进 的内联 <script></script> 中：
- 不要等
DOMContentLoaded—— 此时 HTML 已解析完，样式可能已按错误主题渲染过一帧 - 别在 JS 里动态插入
<link rel="stylesheet">→ 加载延迟必然导致闪 - 所有颜色相关属性（
background-color、color、border-color、box-shadow、svg fill）都必须用var(--bg)，硬编码值会绕过主题系统 - 表单控件（
<input type="range">、<select></select>）和图片不会自动适配，得单独写[data-theme="dark"] input[type="range"]这类规则
哪些细节容易被忽略但线上必翻车
看似简单，但真实项目中卡住最多的是这几处：
- Safari 13.1–14.0 对嵌套在
@layer或预处理器输出中的@media (prefers-color-scheme)有解析 bug，建议单独提一层写 - 部分安卓 WebView（尤其旧版 QQ/微信内置浏览器）完全不支持该查询，需 fallback 到
localStorage检测 - 别用
class="theme-dark"和data-theme="dark"混用 → 容易冲突，统一用data-theme -
prefers-color-scheme只有三个值：light、dark、no-preference（极少出现），别幻想支持sepia或自定义色系
真正难的不是写对那行媒体查询，而是让系统偏好、用户意图、持久化存储、首屏渲染节奏全部对齐——差其中一环，用户就会在页面刚打开的那几十毫秒里，看到一次刺眼的白→黑或黑→白闪动。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
