深色模式Dark Mode适配这件事我前后在六七个项目里做过从最早用一段全局反色脚本糊弄过去到后来老老实实搭一套色彩令牌、逐屏校验对比度中间踩的坑足够写满一个笔记本。半夜十二点用户把系统切成深色模式点开你的页面一道白光直接糊在脸上——这种体验带来的负面记忆比任何一个功能缺陷都更持久。这篇文章想聊的不是“加一条媒体查询就完事”这种层面的东西而是把深色模式适配当成一个完整的工程问题来拆色彩体系怎么搭、三端桌面浏览器、移动端原生壳、内嵌 WebView各自的坑在哪、图片和图表这类“非纯色内容”怎么处理、上线之后怎么回归测试、以及哪些边角场景最容易被漏掉。不管你是刚接手一个存量项目要补深色支持还是从零设计一套设计系统下面这些内容应该都能直接拿去用。1. 深色模式适配到底在解决什么问题1.1 从“反色滤镜”到设计体系的演进逻辑最早期的深色模式实现方式非常粗暴给根元素加一个filter: invert(1) hue-rotate(180deg)整页反色。这套方案五分钟就能上线看起来“支持深色模式”了但实际效果是灾难——品牌 logo 变成诡异的互补色图片里的人脸发青图表里原本靠颜色区分的数据系列全部失去语义。我最早在一个内部工具上试过这种做法上线第二天就收到反馈说“截图发出去同事以为我显示器坏了”。反色方案的根本问题在于它假设颜色只承载“亮度信息”而实际上颜色还承载着品牌识别、状态语义、数据分类这三重信息全都会被破坏。后来主流做法演进成了“双套配色 令牌替换”也就是把颜色从组件里抽出来变成一层可切换的变量。这个转变的关键不在于技术难度而在于认知深色模式不是给浅色界面套一层滤镜而是一套独立的视觉方案它需要单独设计、单独校验。真正成熟的实现是三层结构——最底层是原始色板primitive tokens比如 gray-100 到 gray-900中间层是语义令牌semantic tokens比如 surface-default、text-secondary最上层是组件消费。切换主题时只换中间层的映射关系组件代码一行不动。这样做的好处是后续要加“高对比度模式”或者“护眼模式”只需要再补一套映射不用再动一遍业务代码。我个人的判断标准很简单如果一个项目的深色模式实现里业务组件代码中还能搜到硬编码的十六进制颜色值那这套适配就是不合格的。硬编码是深色模式最大的敌人因为它让“主题”这个概念失去了统一的控制点。1.2 谁该优先适配投入怎么分配不是所有产品都需要立刻做深色模式。我的排序逻辑大致是这样第一优先级是长时间停留的内容消费类界面比如阅读器、文档站、代码编辑器、数据看板——这些场景用户盯屏时间长深色模式对眼睛的友好度直接转化为留存第二优先级是夜间高频使用的工具类应用第三优先级才是停留时间短、以展示为主的页面。投入分配的估算上我给的经验值是如果项目原本已经有比较规范的 CSS 变量体系深色模式的增量工作量大概占整体 UI 开发量的 15% 到 25%如果项目里颜色全是硬编码散落在各处的那这个比例会飙升到 60% 以上因为你需要先做一轮“颜色清点与收敛”这本身就是重构。所以很多团队的实际路径是先做令牌化重构再顺手把深色模式带上而不是为了深色模式去重构。还有一个容易被忽略的决策点深色模式是“跟随系统”还是“独立开关”。我的建议是两者都要——默认跟随系统同时提供手动三态切换自动 / 浅色 / 深色。只做跟随系统会让部分用户困惑“我系统是深色但我就是想让这个 App 亮一点”只做手动开关则会让用户觉得“不智能”。三态是目前的共识方案实现成本也就多几行代码。1.3 三端适配的起点差异桌面浏览器、移动端原生壳、内嵌 WebView这三者的适配起点完全不一样不能一套方案套到底。浏览器端最省心因为有prefers-color-scheme媒体查询和color-scheme属性原生控件滚动条、下拉框、日期选择器、默认背景能自动跟着走。你要做的只是定义好自己的颜色令牌然后监听媒体查询变化。移动端原生壳的复杂度在于系统层面的元素不归你管状态栏文字颜色、导航栏背景、启动图Launch Screen、键盘外观、系统弹窗。这些必须通过原生配置去声明Web 层改 CSS 是动不了的。我见过不少混合开发的项目页面本身深色做得挺好结果启动瞬间白屏一闪体验直接掉档。内嵌 WebView 是最麻烦的一类它同时受宿主 App 的主题设置和系统设置影响而且很多 WebView 默认背景是白色的页面还没渲染完就是一片白。这块的处理必须在原生侧显式设置 WebView 的背景色同时在 Web 侧保证首屏 HTML 的背景色由内联样式决定不能等 CSS 加载完。2. 配色体系深色模式不是把白换成黑2.1 表面色阶与高度感的建立浅色模式里我们靠阴影来表达“层级”——卡片浮在背景之上弹窗浮在卡片之上。到了深色模式阴影几乎完全失效因为深色背景上的黑色阴影对比度极低视觉上根本感知不到。这时候就要换一套语言用表面颜色的明度差异来表达层级。行业里比较通用的做法是“白色叠加法”以基础表面色为底每升一层就叠一层低透明度的白色。常见的档位是 0%、5%、8%、11%、12%、14%、16%对应不同的高度。比如基础背景是#121316叠 5% 白得到约#1E1F23叠 8% 白得到约#232428以此类推。这里有个细节叠加白色而不是直接指定固定色值好处是当你调整基础背景色时所有层级会整体跟随不会出现“背景改了但卡片没改”的割裂感。还有一个反直觉的点基础背景不要用纯黑#000000。纯黑在 OLED 屏幕上确实省电但会带来两个问题——一是卡片和背景的明度差会被拉得过大层级关系显得生硬二是纯黑背景上的浅色文字更容易产生“光晕”感。我一般把最底层定在#0F1013到#16181C这个区间具体取值看品牌调性。真要极致省电可以让用户在设置里单独开“纯黑模式”作为深色模式的一个变体而不是默认。2.2 文字对比度与“晕影”问题对比度这块WCAG 2.1 给的标准是正文文字对比度不低于 4.5:1大号文字18pt 以上或 14pt 加粗不低于 3:1。但实际做下来深色模式如果只盯着这个下限读起来还是累。我的经验是正文对比度控制在 8:1 到 12:1 之间最舒服纯白配纯黑那种 21:1 反而刺眼。举个具体的数值例子。假设深色背景取#121316正文色取#E8EAED按 WCAG 的相对亮度公式算一下先把每个通道归一化到 0 到 1再对小于等于 0.03928 的通道做线性化处理除以 12.92大于的部分用((c 0.055) / 1.055) ^ 2.4然后按 0.2126、0.7152、0.0722 的权重加权求和得到相对亮度 L。算下来背景的 L 约为 0.0065文字的 L 约为 0.823对比度是(0.823 0.05) / (0.0065 0.05)约等于 15.4:1。这个值偏高但可接受。如果把次要文字改成#A2A8B0L 约为 0.388对比度约 7.7:1正好落在舒适区。用途深色下的色值对比度相对 #121316说明正文主文字#E8EAED约 15.4:1略高可降到#DCDEE2次要文字 / 辅助说明#A2A8B0约 7.7:1舒适区推荐禁用态文字#6B7078约 3.6:1仅用于不可交互元素分割线 / 边框rgba(255,255,255,.10)视觉上约 1.3:1不承载信息不要求达标关于深色下的光晕效应halation这是个很实际的问题。浅色文字在深色背景上因为人眼存在轻微散光笔画边缘会向外“发毛”字重越大越明显。所以深色模式下同一套字体建议把字重降一档浅色模式下用 500 的地方深色下用 400浅色下用 400 的深色下可以考虑 350可变字体支持的话。另外不要用纯白#FFFFFF用#E8EAED这类略带灰度的白光晕感会明显减弱。2.3 品牌色与强调色的降饱和处理品牌色是深色模式里最容易翻车的地方。一个在白色背景上很精神的#2563EB蓝色放到深色背景上会显得脏、暗、发闷尤其是用作品牌主色块的时候。原因是对比环境变了同一个颜色在亮背景上感知亮度低于在暗背景上的感知亮度视觉上会“沉下去”。处理方法有两条路。第一条是 HSL 手工调保持色相不变把饱和度降 10% 到 20%明度提到 60% 到 70%。比如hsl(221, 83%, 53%)调成hsl(221, 90%, 72%)视觉上就从“沉闷的蓝”变成“清亮的蓝”。第二条路是用 OKLCH 这类感知均匀的色彩空间做映射color-mix(in oklch, var(--brand) 72%, white 28%)这样调整出来的颜色在感知亮度上和原色更接近不会出现“有的品牌色调完变亮、有的变暗”的不一致。还有一个坑是渐变和多色组合。浅色下常用的从深到浅的渐变在深色下方向往往要反过来改成从浅到深否则渐变末端会融进背景。多色组合里如果把所有颜色统一提亮会丢失原本的区分度正确做法是提亮的同时把饱和度整体压一档让它们看起来是“同一光源下的不同颜色”。2.4 语义化令牌的三层结构设计前面提过三层这里把结构说具体一点。最底层是原始色板命名用中性词比如--gray-900、--blue-500这一层不直接消费。中间层是语义令牌命名用用途词比如--surface-page、--surface-card、--text-primary、--text-muted、--border-subtle、--accent-default、--accent-hover。最上层是组件层比如--button-primary-bg引用--accent-default。关键点是语义令牌必须按“用途”而不是“外观”命名。叫--text-primary是对的叫--text-white是错的——因为深色模式下它就是灰的不是白的一个叫--text-white的变量存着灰色值三个月后接手的人一定会骂人。:root { --surface-page: #ffffff; --surface-card: #f7f8fa; --surface-raised: #ffffff; --text-primary: #17181a; --text-muted: #5b6066; --border-subtle: rgba(0, 0, 0, 0.08); --accent-default: #2563eb; --accent-hover: #1d4ed8; } [data-themedark] { --surface-page: #121316; --surface-card: #1e1f23; --surface-raised: #26272c; --text-primary: #e8eaed; --text-muted: #a2a8b0; --border-subtle: rgba(255, 255, 255, 0.10); --accent-default: #7aa2ff; --accent-hover: #9ab8ff; }注意--surface-raised在浅色下和--surface-page同值是刻意的——浅色下层级靠阴影表达深色下才靠明度。这种“两套模式共用一套变量名但映射逻辑不同”的设计正是令牌体系的价值所在。3. Web 端落地实操3.1 三态主题切换与首屏闪白的根治首屏闪白是深色模式最经典的翻车点。用户设置的是深色页面加载时 CSS 还没解析完浏览器先按默认白底渲染了一帧然后才变黑。这一帧的闪烁在慢网络下能持续几百毫秒体验极差。根治方案是在head里、任何 CSS 请求之前放一段同步执行的内联脚本把主题决策提前到 DOM 构建阶段script (function () { try { var mode localStorage.getItem(theme-mode) || auto; var sysDark window.matchMedia((prefers-color-scheme: dark)).matches; var dark mode dark || (mode auto sysDark); var root document.documentElement; root.dataset.theme dark ? dark : light; root.style.colorScheme dark ? dark : light; } catch (e) { document.documentElement.dataset.theme light; } })(); /script几个细节必须注意。第一这段脚本不能加defer或async必须同步阻塞执行。第二外面必须包try/catch因为隐私模式下访问 localStorage 可能直接抛异常不处理会导致后续所有脚本中断。第三style.colorScheme这一行的作用容易被低估——它告诉浏览器当前的颜色方案滚动条、表单控件、默认背景会自动跟随省掉一大堆手动样式。还有一个配套手段给html加一段内联的默认背景色不给浏览器任何“露出白底”的机会。html>function applyTheme(next) { const root document.documentElement; root.classList.add(theme-transition); root.dataset.theme next; root.style.colorScheme next; window.setTimeout(() root.classList.remove(theme-transition), 260); }html.theme-transition, html.theme-transition *, html.theme-transition *::before, html.theme-transition *::after { transition: background-color 0.25s ease, color 0.25s ease, border-color 0.25s ease, fill 0.25s ease !important; transition-delay: 0s !important; }260 毫秒这个数字不是随便定的它比 250 毫秒的过渡时长久一点点确保过渡真正跑完再移除类不会出现“过渡被截断”的跳帧。另外要尊重用户的减弱动效设置media (prefers-reduced-motion: reduce)下把过渡直接关掉。系统主题变化的监听也别忘了用户在使用过程中切系统主题页面要跟着变const mq window.matchMedia((prefers-color-scheme: dark)); mq.addEventListener(change, (e) { if ((localStorage.getItem(theme-mode) || auto) auto) { applyTheme(e.matches ? dark : light); } });3.3 原生控件、滚动条与表单的同步color-scheme属性解决的是“浏览器自己画的那部分 UI”。声明color-scheme: dark之后滚动条变成深色、select下拉展开是深色、input typedate的日历弹层是深色、input typecheckbox的勾选框是深色。这一行声明能省掉大量手写样式的工作。但有两类控件需要额外处理。一类是文件上传按钮和进度条不同浏览器表现不一致稳妥的做法是自定义样式。另一类是input[typesearch]的清除按钮在深色下有时会是深色图标配深色背景看不见。我的做法是统一用appearance: none关掉原生外观自己画。滚动条如果要自定义注意::-webkit-scrollbar在新版浏览器里已经逐步被标准属性替代可以用scrollbar-color和scrollbar-widthhtml { scrollbar-color: rgba(255, 255, 255, 0.2) transparent; scrollbar-width: thin; }文本框的自动填充背景也是个老问题。浏览器自动填充会强制加一层淡黄色或淡蓝色背景深色模式下特别刺眼。可以用box-shadow内阴影覆盖input:-webkit-autofill, input:-webkit-autofill:hover, input:-webkit-autofill:focus { -webkit-text-fill-color: var(--text-primary); -webkit-box-shadow: 0 0 0 1000px var(--surface-card) inset; transition: background-color 9999s ease-out; }那个9999s的过渡是个经典 hack作用是把浏览器自动填充的背景色变化“冻结”在起始状态本质上是用时间换样式。看起来丑陋但有效业界通用。3.4 图片、阴影、边框的差异化处理纯色元素好办图片这种“内容自身带颜色”的东西就麻烦了。一张在白底上设计的截图放到深色背景上会变成一个发光的方块非常扎眼。方案分级处理。最省事的是给全站图片加一层轻微压暗filter: brightness(0.85) contrast(1.02)效果是让图片整体“沉”下去一点不刺眼。注意要排除掉本身就有透明背景的图标否则会显得脏。第二级是用picture提供两套图源picture source srcset/img/chart-dark.png media(prefers-color-scheme: dark) img src/img/chart-light.png alt数据趋势 /picture这个方案对信息图、插画、产品截图最合适成本是资源体积翻倍所以只对关键图用。第三级是 SVG 图标直接改用currentColor填充字体颜色变了图标自动跟着变这是最优解但要求图标本身是内联 SVG 或者通过 CSS mask 引入。阴影的处理前面提过深色下改成“低透明度黑色大扩散 高光内阴影”的组合[data-themedark] .card { background: var(--surface-card); border: 1px solid var(--border-subtle); box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.04), 0 8px 24px rgba(0, 0, 0, 0.45); }那条内阴影是关键它在卡片顶部画出一条极细的高光线模拟“光源从上方照下来”的物理逻辑让卡片有厚度感而不是一张贴纸。边框的存在也是为了在阴影失效时兜底——即使阴影完全看不见边框也能把元素的边界划出来。4. 移动端与原生壳的适配细节4.1 系统跟随机制与状态栏联动移动端两大系统都提供了“跟随系统深色”的开关但实现方式差异不小。iOS 侧是在配置里声明UIUserInterfaceStyle如果设成Automatic系统会跟随全局设置也可以代码里对单个视图控制器设置overrideUserInterfaceStyle做局部覆盖。Android 侧是通过AppCompatDelegate.setDefaultNightMode()控制取值有“跟随系统”“强制浅色”“强制深色”几种。这里有个必须提前决定的事要不要关掉系统的“强制深色”force dark。这个功能会在应用没有主动适配深色时由系统自动做一套颜色反转效果和浏览器那个反色滤镜差不多能看但不好看。如果你的项目已经认真适配过了一定要显式关掉它否则系统会在你精心调过的界面上再糊一层反色前功尽弃。Android 侧是在主题里设android:forceDarkAllowedfalseiOS 侧则是确保没有开启任何自动转换选项。状态栏的联动是最容易漏的。深色模式下状态栏文字必须是浅色浅色模式下必须是深色否则白底白字直接看不见。这个要在主题切换的回调里同步设置并且要注意刘海屏、挖孔屏的安全区颜色也要跟着变。我见过一个案例页面适配得挺好但状态栏图标一直是黑色深色模式下几乎不可见用户反馈是“顶部时间看不见了”排查了半天才发现是漏了这一行。4.2 启动图与 WebView 的白闪问题启动图Launch Screen在移动端是独立于应用的它在应用进程启动之前就已经显示所以它的背景色必须静态配置。做法是准备两套启动图资源浅色一套深色一套在配置里指定。如果用的是 storyboard 或者配置文件方案记得检查深色下的背景色是否也跟着改了。WebView 的白闪问题更隐蔽。原生壳打开一个 WebViewWebView 的默认背景是白色页面 HTML 开始解析之前那段时间就是一片白。解决方案是在原生侧显式设置背景色同时 Web 侧的 HTML 根元素必须有内联背景色。// 移动端原生侧示意 webView.setBackgroundColor(isDark ? 0xFF121316 : 0xFFFFFFFF);同时 Web 侧的html上要有和原生一致的背景色。两边不一致的话会出现“原生是深灰、WebView 是纯黑”的色差断层滚动到边界时特别明显。这个色值建议用一个共享常量管理原生和 Web 都从这个常量取避免两边各改各的。还有键盘外观。深色模式下弹出浅色键盘视觉上很割裂。移动端都有对应的设置项可以让键盘跟随应用主题别忘了加。4.3 运行时切换的刷新策略用户在应用内切换主题时最理想的效果是即时生效、不闪屏、不丢状态。Web 端改个>const palette isDark ? [#7AA2FF, #F2B36B, #7FD1AE, #C69BFF, #E88B9A, #8FD4E8] : [#2563EB, #C2410C, #0F766E, #6D28D9, #BE123C, #0E7490];第三个问题是 canvas 背景。绝大多数图表库默认画布背景是透明的透明背景在深色容器上会自动透出深色看起来没问题——但如果图表被放在卡片里卡片又有自己的背景色就会出现“图表背景比卡片浅一点”的色块。稳妥做法是显式设置图表背景色为transparent而不是留空或者直接设成和卡片一致的颜色。5.2 代码块与富文本的独立主题技术类站点绕不开代码块。代码高亮本质上是“多色文本”和图表一样需要独立主题。亮度、饱和度的处理逻辑是一样的但有个额外的坑很多高亮主题的注释色是深灰色在深色背景上对比度可能只有 2:1 左右完全读不清。选主题时一定要单独验一遍注释色的对比度。富文本内容里还有几个特殊元素。引用块在浅色下通常用左侧竖线加浅灰背景深色下背景色要改成“比页面背景略亮”而不是“略暗”否则会显得像凹陷的坑。行内代码的背景色同理。表格的斑马纹在深色下要降低对比用 2% 到 3% 的白色叠加就够用多了会显得破碎。5.3 第三方组件与嵌入内容的兜底第三方嵌入内容是深色适配的黑洞。你没法控制它的样式它也不知道你的主题。常见的有内嵌的视频播放器、地图组件、客服聊天窗口、支付表单、iframe 嵌入的外部页面。处理策略分三层。第一层是“支持透传”很多第三方组件提供了主题参数优先用官方参数。第二层是“CSS 覆盖”用:root[data-themedark] iframe这类选择器加滤镜或者背景色兜底但这只对同源内容有效跨域 iframe 动不了。第三层是“容器包装”给第三方内容套一个边框或者深色背景容器即使它内部是白的视觉上也被框住了不至于太突兀。我实测下来最有效的其实是“提前沟通”——在设计阶段就把深色模式作为需求提给第三方供应商比上线后再去糊 CSS 强一百倍。实在改不了就在深色模式下给这类区域加一个明显的“浅色内容区”标识让用户有心理预期。6. 常见问题与排查实录6.1 深色模式问题速查表现象大概率原因处理方式首屏白屏闪一下主题脚本在 CSS 之后执行把脚本移到head最前面同步执行部分文字看不清组件里硬编码了深色文字色全局搜#0、#1、#2开头的色值逐个替换滚动条还是白色没声明color-scheme根元素加color-scheme: dark下拉框展开是白底原生控件未跟随同上color-scheme会自动处理卡片没有层次感阴影在深色下失效改用表面色阶 边框 内高光图片像发光方块图片亮度未适配加filter: brightness(.85)或换深色图源图表网格线消失网格线色值沿用浅色改为rgba(255,255,255,.1)左右iframe 里一片白跨域内容不受控外层加深色容器包装或联系提供方支持输入框自动填充变色浏览器填充背景用内阴影覆盖法冻结背景切换主题时页面抖动全局过渡类没及时移除用定时器在过渡结束后移除状态栏图标看不见原生侧未同步在切换回调里同步状态栏样式深色下切换页面白闪WebView 背景色未设置原生侧显式设背景色6.2 自动化回归与视觉验证深色模式的回归测试如果靠人工点一定会漏。我的做法是把它接进视觉回归流程。第一层是截图对比。用自动化工具在浅色和深色两种模式下各跑一遍核心页面把截图存档改代码后对比差异。这里要配置好colorScheme模拟参数比如在自动化脚本里page.emulateMedia({ colorScheme: dark })让浏览器按深色偏好渲染。第二层是颜色合规扫描。写个脚本遍历所有渲染后的元素把计算样式的背景色和文字色取出来按前面说的相对亮度公式算对比度低于阈值的直接报出来。这个脚本能揪出大量“肉眼没注意但确实看不清”的问题比如禁用态按钮、占位符文字、小号辅助说明。第三层是硬编码检查这个放在代码规范层面用正则扫源码里残留的十六进制颜色出现在组件文件里就报警。一开始可能报几百条慢慢清理清完就能长期守住。6.3 偏好持久化与降级策略存储策略看着简单实际有三个坑。第一个坑是存储不可用。隐私模式、存储配额满、某些企业策略下 localStorage 都会抛异常。所有读写都必须包try/catch失败时降级到“跟随系统”不能让整个应用崩掉。第二个坑是“系统变了但用户手动设过”。逻辑上要区分“用户明确选择了深色”和“用户没选过所以跟随系统”这两种状态不能混。存储里存的是三态值auto/light/dark而不是布尔值这样才够表达。第三个坑是跨设备同步。如果产品有多端用户在一端设了深色另一端打开还是浅色会让人觉得设置没生效。这件事可做可不做如果需要做就在用户配置接口里加一个字段本地存储作为优先、服务端配置作为兜底注意处理好“本地和服务端冲突时谁优先”的规则。7. 几个最容易被漏掉的边角场景打印样式是个经典盲区。深色模式下用户按了打印如果没做处理很可能打出一张全黑背景、浅灰文字的纸既费墨又看不清。做法是在打印媒体查询里强制回到浅色media print { :root, [data-themedark] { --surface-page: #ffffff; --text-primary: #000000; --border-subtle: rgba(0, 0, 0, 0.15); } }导出 PDF 同理。如果导出走的是页面截图或者浏览器打印通道一定要在导出前临时切到浅色主题导出完再切回来。系统级高对比度模式也要单独考虑。部分用户会开启“强制颜色”或“高对比度”辅助功能这时候浏览器会用自己的调色板覆盖你的颜色background-image和box-shadow可能整个失效。这类模式下不要跟系统对着干老老实实用forced-colors媒体查询做适配重点保证边框可见、焦点态清晰别让界面变成一片纯色块。最后提一句纯黑模式。不少用户偏爱 OLED 屏上的纯黑因为省电且对比强烈。如果你的产品用户量大可以考虑在设置里给一个“纯黑背景”开关把最底层的--surface-page单独切成#000000其他层级保持不变。这个开关不影响整体结构实现成本很低但对于喜欢它的用户感知价值很高。我给一个小工具做过这个开关后台数据显示开启比例不到 8%但这 8% 的用户留存明显更高——这类“小众但高粘性”的偏好做起来划算。