仅靠@media (prefers-color-scheme: dark)无法实现手动切换且易闪屏，必须结合:root变量、初始HTML class或JS提前注入；需定义全局变量、用data-theme控制覆盖、保留媒体查询作fallback，并注意边框语法、过渡动画和color-scheme声明。
仅靠 prefers-color-scheme 媒体查询无法实现“用户可手动切换”的深色模式，它只响应系统设置，且加载时可能闪屏——必须配合 :root 变量 + 初始 HTML class 或 JS 提前注入才能可靠落地。
为什么 @media (prefers-color-scheme: dark) 单独用会出问题
这个媒体查询本身没问题，但常见误用导致效果不可控：
- 把颜色值硬写在组件里，比如
.card { background: #1e1e1e; }，@media块里再覆盖也无效——CSS 优先级没变，浏览器按原始声明渲染完才查媒体查询 - 变量没定义在
:root，而是写在.dark .card里，那媒体查询根本触不到变量作用域 - iOS 13 以下 Safari 不支持该查询，纯依赖它会导致老设备永远显示浅色
- 用户刚切到深色系统，网页刷新后才生效；中间没有过渡，肉眼可见白→黑一跳
:root 变量必须定义在顶层，且只覆盖值，不写选择器
所有主题相关样式必须从 :root 取值，媒体查询只负责改变量，不写具体组件规则：
:root {
--bg: #fff;
--text: #333;
--border: #e0e0e0;
}
<p>@media (prefers-color-scheme: dark) {
:root {
--bg: #1a1a1a;
--text: #f0f0f0;
--border: #333;
}
}</p><p>body {
background: var(--bg);
color: var(--text);
border: 1px solid var(--border); /<em> 注意：不能漏 solid </em>/
}这样写，浏览器解析 CSS 时就已知变量值，无需等 JS 注入 class，避免首帧闪烁。
立即学习“前端免费学习笔记（深入）”；
如何让 prefers-color-scheme 和用户手动选择共存
不能二选一，得叠加判断：系统偏好做默认，用户操作做覆盖。关键在 HTML 初始状态和 JS 执行时机：
- 服务端渲染或静态 HTML 中，直接根据请求头或 localStorage 写
<html data-theme="dark">，不是等 JS 加载后再加 - 纯前端项目，JS 必须在
<head>里尽早执行：document.documentElement.setAttribute('data-theme', savedTheme || 'light') - CSS 里用
[data-theme="dark"]覆盖:root，而不是只信@media—— 这样用户点按钮切主题时，data-theme改变，变量立即重算 -
prefers-color-scheme的媒体查询仍保留在 CSS 中，作为 fallback：当 localStorage 为空时，它提供初始值
容易被忽略的细节：边框、过渡、原生控件
这些地方一疏忽，深色模式就“看起来怪”：
-
border: 1px var(--border)是无效语法，必须写全border: 1px solid var(--border)，否则边框消失 - 所有用变量的地方都要加
transition，比如background: var(--bg); transition: background 0.2s;，否则切换生硬 - 记得加
color-scheme: light dark到:root或html，否则表单控件（如<input type="range">）在深色下仍用浅色样式 - 检查 DevTools 的 Computed 面板，确认
border-color最终值是否真为#333，而不是因为对比度太低“看不见”
真正难的不是写对那几行媒体查询，而是确保变量作用域干净、HTML 初始状态正确、原生控件同步响应——这三处任一遗漏，都会让用户在某个设备或操作路径下看到错乱的主题。
