@media (prefers-color-scheme: dark) 在移动端需满足css外链引入且不嵌套，颜色必须通过css变量并用var()调用，配合color-scheme声明和data-theme接管才能真正生效。
如何用 @media (prefers-color-scheme: dark) 检测移动端暗黑模式
它不是“监听”，而是页面加载时读取系统设置的一次性声明——iOS 13.3+、Android 10+ 的 WebView 和 Safari/Chrome 都支持，但必须满足两个硬条件：CSS 文件得在 里用 <link> 引入；媒体查询不能写在 @import 后面或动态插入的样式表里。常见失效是因为开发者把规则塞进 JS 创建的 <style></style> 标签，或者用了嵌套写法如 @media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }，Safari 12.1 之前直接忽略。
为什么写了 @media (prefers-color-scheme: dark) 却没切换颜色
根本原因不是媒体查询没匹配，而是颜色没走变量通路。比如你写了：
:root { --bg: #ffffff; }
@media (prefers-color-scheme: dark) {
:root { --bg: #121212; }
}
body { background: #ffffff; }
——body 用的是硬编码值，--bg 变量根本没被消费。必须改成 background: var(--bg); 才生效。另外注意顺序：@media 块得放在所有默认 :root 声明之后，否则会被后续无条件的 :root 覆盖。
-
:root里每个变量都得有浅色默认值，漏一个（比如没定义--text-secondary），深色下var(--text-secondary)就 fallback 到浏览器默认灰，和深背景撞成低对比 - 别在媒体查询里定义新变量名（如
--bg-dark-only），浅色环境读不到，var(--bg-dark-only)直接失效 - 移动端 WebView（尤其旧版 WKWebView）可能压根不传系统偏好，需用
window.matchMedia('(prefers-color-scheme: dark)').matches实测返回值
怎样让暗黑模式真正满足高对比度可访问性
硬写 #121212 + #e0e0e0 是陷阱：iOS 高对比度模式下文字会变粗、背景变纯黑，而你的浅灰字在纯黑底上对比度暴跌。正确做法是优先用系统语义色：
- 用
Canvas替代#121212作背景，CanvasText替代#e0e0e0作文本色——它们随系统高对比度开关自动调整亮度层级 - 必须加
html { color-scheme: light dark; }，否则<input>、<select></select>等原生控件边框、滚动条仍保持亮色 - 如果必须自定义色，改用
lab(20% 0 0)这类现代函数，比rgb()更可控亮度；避免hsl(240 5% 10%)这种低饱和低亮度组合
手动切换按钮与系统偏好冲突怎么办
prefers-color-scheme 是只读信号，点了“切暗黑”按钮后刷新就回退。解决方案是用 data-theme 属性接管控制权，并让 CSS 规则按优先级排序：
- 初始化时先读
localStorage.getItem('theme')，有值就设document.documentElement.setAttribute('data-theme', 'dark') - 没值才 fallback 到
matchMedia('(prefers-color-scheme: dark)').matches - CSS 中写
html[data-theme="dark"] { --bg: #121212; }，并确保这条规则在@media (prefers-color-scheme: dark)之后，靠层叠优先级压制系统查询结果 - 监听系统变化时，只在用户没手动选过主题时才响应
change事件，避免覆盖用户选择
最易被忽略的点：所有颜色必须统一走变量，包括 SVG 的 fill、图片的 filter: brightness()、甚至伪元素的 content 颜色——漏掉任意一处，都会在暗黑+高对比度下暴露低可访问性问题。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
