移动端深色模式必须同步初始化data-theme、声明color-scheme、变量全挂:root，三者缺一不可；否则iOS Safari首屏渲染错乱、原生控件不适配、样式闪动或失效。
直接说结论：只写 @media (prefers-color-scheme: dark) 在移动端基本等于没做——必须同步初始化 data-theme、声明 color-scheme、变量全挂 :root，三者缺一不可。
为什么写了 @media (prefers-color-scheme: dark) 却在 iOS Safari 里没反应
不是语法错，是渲染时机断层。iOS Safari 首次渲染时还没读取系统偏好，:root 变量已按浅色默认值计算完毕，等媒体查询生效再重绘，用户就看到“白→黑”闪动，甚至部分样式压根不更新。
- 必须在
<head>最顶部内联轻量 JS，用window.matchMedia('(prefers-color-scheme: dark)')立即检测并设置document.documentElement.setAttribute('data-theme', 'dark') -
@media (prefers-color-scheme: dark)规则本身不能动态监听切换，它只在页面加载时触发一次；如需响应系统实时切换，得额外加.addEventListener('change', ...)，但多数场景只需首屏正确即可 - 别把媒体查询嵌套在
@media (max-width: 768px)里——Safari 12.1 之前完全不识别，移动端兼容风险极高
color-scheme 和 meta 标签为什么不能省
color-scheme: light dark 声明在 CSS 里，只告诉浏览器“我支持双模式”，但它不触发原生控件适配；真正开关是 <meta name="color-scheme" content="light dark">，且必须写死在 <head> 最顶部，JS 动态插入无效。
- 漏掉
<meta>标签，<input>、<select>、滚动条 thumb、<progress>轨道等 UA 控件在深色系统下仍保持浅色外观 -
html { color-scheme: light dark; }必须配合<meta>才生效，单独写无意义 - 系统语义色（如
Canvas、CanvasText）只有在这两者都存在时才会被 UA 自动映射，硬写#121212会丢失高对比度适配能力
:root 变量定义和覆盖的顺序陷阱
变量必须全部定义在 :root，且浅色默认值要先写、深色覆盖要后写；任何遗漏或顺序颠倒都会导致部分元素 fallback 到浏览器默认值（比如白底黑字糊成一片）。
立即学习“前端免费学习笔记（深入）”；
- 错误写法：
:root { --bg: #121212; }→ 浅色模式下所有var(--bg)都继承深色值 - 正确写法：先
:root { --bg: #ffffff; --text: #333333; --border: #e0e0e0; }，再@media (prefers-color-scheme: dark) { :root { --bg: Canvas; --text: CanvasText; --border: Canvas; } } - 所有用到变量的地方（
fill、background、伪元素、SVG）都得靠var(--xxx)，不能只改body或某个 class - 第三方组件（如 Vant、NutUI）若依赖自己的
.dark类，必须提高选择器优先级，例如用html[data-theme="dark"] .nut-button而非简单.nut-button
哪些地方最容易被忽略但实际影响体验
光调背景和文字颜色只是起点。图片发灰、输入框边框消失、代码块白底、SVG 图标不反色——这些才是移动端深色模式上线后被用户吐槽最多的点。
-
<img>加background: var(--bg);防透明 PNG 在深色背景下边缘发虚 -
<input>、<textarea>必须显式重置color、background、border-color，appearance: none 不解决根本问题 - 滚动条需单独写
::-webkit-scrollbar-thumb，且值也应为var(--scroll-thumb)或CanvasText - 内联 SVG 图标必须用
fill: currentColor或fill: var(--icon-fill)，filter: invert(1)会破坏可访问性
最麻烦的不是写多少代码，而是所有变量、所有选择器、所有原生控件都得对齐同一套初始化逻辑——data-theme 属性、<meta>、color-scheme、:root 变量顺序，四个点只要一个没对上，移动端深色模式就处于“看起来差不多，实则处处漏光”的状态。
