最简写法是@media (prefers-color-scheme: dark)，需置于css顶层，不可嵌套；支持light、dark、no-preference三值，漏括号或误作css声明均无效。
prefers-color-scheme 媒体查询怎么写才生效
直接用 @media (prefers-color-scheme: dark) 是最简方式，但它只在 CSS 文件或 <style></style> 块里起作用，且必须是顶层规则（不能嵌套在 @supports 或其他媒体查询内部）。浏览器一加载就解析，不依赖 JS，所以优先级高、无闪屏。
常见错误：写成 @media prefers-color-scheme: dark（漏括号）或放在 :root 选择器里当声明用（语法非法）。
- 支持值只有
light、dark、no-preference，没有auto或system -
no-preference极少见，通常可忽略，不用兜底 - 部分旧版 Safari（
CSS 变量怎么配合 prefers-color-scheme 动态赋值
不能在媒体查询里“定义变量”，但可以在 :root 中预先声明，再用媒体查询覆盖。关键点是：所有主题相关变量必须在 :root 下声明初始值，否则暗色模式下未覆盖的变量会退回到继承值或默认值，导致样式断裂。
示例：
:root {
--bg-primary: #fff;
--text-primary: #111;
}
@media (prefers-color-scheme: dark) {
:root {
--bg-primary: #1a1a1a;
--text-primary: #eee;
}
}
- 不要用
.dark-mode类模拟，那属于手动切换，不是系统级自动响应 - 变量名保持中性（如
--bg-primary），避免带-light/-dark后缀，否则后期扩展高对比度模式时难维护 - 如果用了 CSS-in-JS（如 styled-components），需确认其 SSR 是否保留媒体查询逻辑，否则首屏可能错配
JavaScript 检测变化并触发重绘的边界情况
监听 window.matchMedia 的 change 事件确实能捕获系统主题切换，但仅适用于需要运行时逻辑的场景（比如初始化 Canvas 背景、调整第三方图表库主题）。纯 CSS 变量切换不需要 JS 干预。
- 务必在页面加载后立即检查一次
matchMedia('(prefers-color-scheme: dark)').matches，避免首次渲染用错主题 - 监听器需保存引用，以便后续
removeEventListener，否则可能内存泄漏 - 某些桌面端 Linux 发行版或 Windows 10/11 的“深色模式仅限应用”设置下，
matchMedia可能始终返回false，此时无法 fallback
为什么有些元素没跟着变色？排查顺序
最常被忽略的是硬编码颜色值。CSS 变量只影响用了 var(--xxx) 的地方，而 background: #fff、color: black 这类字面量完全绕过主题机制。
- 检查是否对
svg的fill、stroke属性用了固定色值（应改用currentColor或变量） - 表单控件（
input、button）默认样式由 UA stylesheet 控制，部分浏览器在暗色模式下仍强刷白底，需显式重置background和color - 图片资源不会自动反转，
prefers-color-scheme不影响<img src>，如有需要得靠picture+source media
系统主题切换不是魔法，它只驱动你写下的媒体查询和变量——漏掉一处硬编码，就有一处不跟随。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
