prefers-color-scheme 仅响应系统深色设置，不支持手动切换或 localstorage 覆盖；常见失效原因包括css优先级不足、动态插入时机不当、嵌套于@layer/@container中，且需配合js实现用户主动切换逻辑。
直接用 @media (prefers-color-scheme: dark) 就能生效，但必须注意它只响应系统级深色设置，且不支持手动切换或 localStorage 覆盖。
为什么 prefers-color-scheme 有时不触发
常见错误是把媒体查询写在 CSS 文件末尾却没加 !important，或者被更高优先级的选择器覆盖；更关键的是：它只读取操作系统/浏览器的深色偏好，不会监听 JS 修改的 class 或自定义主题开关。
- 检查系统设置是否真正开启深色模式（macOS 的“深色外观”、Windows 的“深色模式”、Chrome 的
chrome://flags/#enable-force-dark不算标准路径） - 确保 CSS 是通过
<link>引入或内联在中，动态插入的 style 标签可能因执行时机错过初始匹配 - 避免嵌套在
@layer或@container内——目前主流浏览器不支持媒体查询在这些规则中条件生效
@media (prefers-color-scheme: dark) 的典型写法
它不是开关，而是条件样式块，所有声明都仅在匹配时应用。不要试图在里面写 color-scheme: dark（那是 HTML 属性，用于表单控件默认样式）。
@media (prefers-color-scheme: dark) {
:root {
--bg: #121212;
--text: #e0e0e0;
}
body {
background-color: var(--bg);
color: var(--text);
}
img[alt*="logo"] {
filter: brightness(0.8) contrast(1.2);
}
}
- 推荐用 CSS 自定义属性统一管理颜色变量，方便后续扩展 light/dark/high-contrast 多模式
- 慎用
filter批量反色（如invert(1)），会破坏图片语义和图标可访问性 - 对 SVG 内联图标，优先改
fill和stroke，而非包裹一层 filter
如何兼容手动切换 + 系统偏好双逻辑
纯 prefers-color-scheme 无法满足“用户点按钮切深色”的需求。必须配合 JS 检测并写 class 到 上，再用属性选择器覆盖：
/* 默认按系统 */
@media (prefers-color-scheme: dark) {
:root { --bg: #121212; }
}
<p>/<em> 手动开启深色（优先级更高） </em>/
html.dark-theme {
--bg: #121212;
}
html.light-theme {
--bg: #ffffff;
}</p>
- JS 切换时务必同时设置
localStorage并同步document.documentElement.className - 首次加载需 JS 读取 localStorage 并立即加 class，否则会有闪屏（CSS 还没加载完就渲染了浅色）
- 不要用
matchMedia监听后立刻改 class——那只是响应系统变化，不是实现手动控制
最易被忽略的一点：深色模式下，background-color 和 color 只是基础，border-color、box-shadow、caret-color、accent-color（用于 checkbox/range）全都需要单独适配，否则会出现灰色边框糊在深灰背景上、光标看不见、滑块不可见等实际问题。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
