做前端的时间越长我越觉得暗色模式是一个特别容易被低估的功能。表面上看它就是“把页面背景从浅色换成深色”不少人第一反应都是“这不就是加两行CSS的事吗”。可真正上手做一次你会发现从设计定位、色彩体系、状态管理到渲染时机每一环都有讲究做不好用户切过去一眼就难受。我自己在维护某内部组件库时暗色模式前后做了三轮大改才沉淀出今天这套比较顺手的流程。这个系列正好写到第6篇我借这个机会把完整思路整理出来接着前面几篇已经铺好的基础设施这次专门聊暗色模式。这篇内容对你的参考价值在于不管你是要给企业后台加一个夜间阅读模式还是做个人博客的亮暗切换又或者是在组件库里把暗色模式做成全局基础设施这套方法都可以直接落到你自己的项目里。我会按做项目的实际顺序来写——先拆目标再设计调色板然后选技术方案接着处理状态管理与防闪白最后是一份可以照抄的验收清单。文章里没有空话基本都是踩过坑之后总结出来的结论和代码。1. 先拆目标暗色模式真正要解决的是什么1.1 从用户场景反推真实需求做技术的人很容易掉进“实现细节”的坑里一上来就研究CSS变量怎么定义、JS怎么监听系统偏好。但暗色模式这个功能起点压根不在代码里而在用户场景里。用户为什么需要暗色模式我归纳下来基本是三类动因。第一类是舒适度深夜躺在床上刷手机、在光线很暗的房间里看文档纯白背景的屏幕等于一个小型手电筒瞳孔被强光反复刺激眼睛很快就酸了。第二类是省电OLED屏幕上黑色像素不发光大面积深色界面确实能降低功耗这个在移动端尤其明显。第三类是审美偏好有些用户就是觉得深色界面更专注、更“高级”哪怕在白天也会主动切过去。如果把这些场景倒推成产品需求结论就很清楚了一个合格的暗色模式不是“把页面变黑”而是让用户在深色环境下依然能像在亮色模式下一样高效地获取信息。这意味着文字的对比度、界面元素的层级感、hover和focus这类交互状态、甚至图标和图片的可辨识度全部都要重新设计一遍。它不是一次自动翻转而是一套与亮色模式平行存在的视觉方案。1.2 三个需求层次对应三种实现成本我在不同项目里接触过暗色模式的各种做法总结下来用户侧的需求大概可以分为三个层次每个层次的实现成本和产品形态差别很大。需求层次表现形态典型场景实现成本跟随系统没有手动开关操作系统切到深色页面跟着变深色内容型网站、博客、文档站低手动切换页面内提供一个开关用户自己选亮或暗选择被记住需要品牌强统一的站点、编辑部后台中自适应混合默认跟随系统用户手动切换后以手动选择为准组件库、高频使用的C端产品、工具类应用高这三个层次不是随便定的它们分别对应了不同的产品哲学。跟随系统是把决定权交给操作系统用户在你的页面上不需要做任何事手动切换是把决定权完全交给用户但用户得自己记住想要什么混合模式则是两者的综合——系统给你一个合理的默认值用户又随时可以覆盖它。1.3 动手写代码前先回答三个问题结合我自己的经验任何项目开始做暗色模式之前都应该先回答三个问题。第一目标用户会不会在深色环境下长时间使用你的界面如果产品主要使用场景是明亮办公环境暗色模式的优先级可以放很低如果是阅读类、工具类、社区类产品那暗色模式就属于基础体验不是加分项。第二产品需不需要给用户手动开关这个问题的判断依据是品牌一致性和用户控制欲。像很多内容消费产品用户就是要夜间躺着看他未必愿意去改系统设置所以应用内开关几乎是必须的。而有些品牌感极强的官网页面效果是精心调过的结论可能是“不管系统怎么变我们只提供亮色”这也是一种合理选择。第三品牌主色在深色背景下还能不能保持辨识度这个问题常被忽略。很多品牌的VI色是为了白底设计的放到深色背景上要么太亮刺眼要么饱和度失衡需要在暗色主题里专门准备一套品牌色的“暗色版本”。这三个问题直接决定了后面的技术选型。我把它写在最前面是因为见过太多项目一上来就写CSS后来发现要么缺开关要么开关做了但系统联动没做最后推倒重来。先花十分钟把目标想清楚后面省的是几天的返工时间。2. 调色板设计暗色模式的根基是一套语义化变量2.1 硬编码颜色是暗色模式的头号敌人很多老项目接入暗色模式时最头疼的问题不是技术做不到而是代码里到处散落着#fff、#333这类写死的颜色。你没法全局搜一下“白色”就替换完因为有的白色是背景有的白色是文字颜色有的白色只是某个描边的反光效果。面对这种代码暗色模式根本不是“加一套变量”能解决的你得先把所有硬编码颜色改造成变量。正确的做法是放弃以“颜色本身”命名改用以“语义”命名。所谓语义化变量就是变量名描述的是“这个颜色用什么”而不是“这个颜色是什么”。:root { --bg-canvas: #F7F8FA; /* 页面最底层背景 */ --bg-surface: #FFFFFF; /* 卡片、面板等承载内容的表面 */ --bg-overlay: rgba(0,0,0,0.55); /* 遮罩层 */ --text-primary: #1D2129; /* 正文文字 */ --text-secondary: #5B6472; /* 次要说明文字 */ --text-disabled: #9AA1AB; /* 禁用状态文字 */ --border-divider: #E6E8EB; /* 分割线、描边 */ --accent-brand: #3B82F6; /* 品牌强调色 */ --success: #16A34A; --warning: #D97706; --danger: #DC2626; }组件里只引用var(--bg-surface)、var(--text-primary)这类语义变量。亮色和暗色主题就只是这组变量在不同作用域下的两套映射关系。这样设计之后切换主题本质上只是切换一组变量的值组件代码一行都不用动。2.2 暗色模式里的层级是靠“更亮”来表达的这里需要解释一个视觉原理。在亮色模式下我们判断“这个卡片浮在页面上”主要靠的是阴影——卡片在白色背景上投下一个柔和的灰色阴影层次感就出来了。但到了暗色模式背景本身已经是深色的黑色阴影几乎不可见再用“加深阴影”的方式表达层级基本是无效的。所以暗色模式里有个反直觉的规则层级越高表面颜色反而越亮。就像在一个暗房间里离你越近的物体会被光线照得更亮离你越远的背景则隐入黑暗。应用到界面上就是页面底色最深普通卡片稍亮一点弹层和浮层最亮。层级亮色主题暗色主题说明页面底色#F7F8FA#121417最底层卡片/面板#FFFFFF#1D2024比底色亮一档弹层/浮层#FFFFFF 强阴影#262A30最高层最亮悬浮/按压态黑色遮罩4%白色遮罩6%用遮罩而非改色这个表格里的数值是我自己在实践中比较顺手的起点不是标准答案。不同产品的视觉风格不同但“层级越高越亮”这个原则是通用的。你只需要在调色板里定义三到四档表面色用的时候严格按层级取用不要在组件里自己发明新的灰色。2.3 对比度不是玄学直接按标准算暗色模式里最容易翻车的其实是次要文字。主文字用白字配深底通常没问题但很多设计会把次要说明文字调得太暗想着“深色模式嘛次要文字暗一点不打扰”结果对比度跌破可读性底线用户在夜间模式下看辅助信息简直是受刑。对比度这块直接参考可访问性领域的通行标准就行。正文文本与背景的对比度至少要达到4.5:1大号文字一般指18号或14号加粗以上和界面组件图标要求放宽到3:1。这不是“可望不可及”的要求而是一个实打实的验收入口。拿我上面给的暗色变量算一下#121417的背景配合#E4E7EC的正文文字对比度大概在12:1左右算是非常宽裕配合#9AA1AB这种次要文字对比度也能到6:1左右也合格。但如果你把次要文字调成#6B7280配深色背景可能就只剩下3:1左右了这就不适合作为正文使用。另外我特别提醒一句不要用纯黑#000配纯白#FFF。纯黑背景在OLED屏上虽然省电但黑白两极的强烈对比会产生光晕感深色环境下反而累眼睛。用带一点灰的深色比如#121417作为底色配合带一点灰的白色比如#E4E7EC作为文字视觉上会舒服很多。2.4 品牌色大面积降饱和小面积保活力品牌色在暗色模式里是一个容易被忽视的坑。很多品牌蓝、品牌红是在白色底上验证过的放到深色底上原封不动搬过去会有两种问题要么太亮一大片高饱和色块在夜间非常刺眼要么和深色背景的融合度不够显得“浮”。我的处理原则是大面积使用的品牌色比如按钮底色、导航栏背景要降低饱和度和亮度让它在深色背景下不刺眼小面积使用的品牌色比如链接文字、图标、焦点描边则保持足够的明度和饱和度因为小面积元素需要靠颜色在深色背景里跳出来。这里可以用CSS的color-mix()函数来生成暗色模式下的品牌色变体不需要在每个主题里手动抄一份十六进制色值:root[data-themedark] { --accent-brand: #60A5FA; /* 亮色模式的品牌色提亮一档 */ --accent-brand-hover: color-mix(in srgb, var(--accent-brand) 85%, #FFFFFF); --accent-brand-active: color-mix(in srgb, var(--accent-brand) 75%, #000000); }color-mix()可以把品牌色和白色或黑色按比例混合hover态亮一点、按压态暗一点这样交互状态的层次感就出来了而且品牌色换版本时暗色模式会自动跟着调整不用再手算一遍。3. 技术选型三套方案我最后选了混合模式3.1 方案A纯跟随系统只有媒体查询纯CSS方案的核心就是prefers-color-scheme媒体查询:root { /* 亮色变量 */ } media (prefers-color-scheme: dark) { :root { /* 暗色变量 */ } }这个方案的优点非常突出零JavaScript没有执行时机的问题不存在闪白实现成本最低。如果你的产品定位就是“完全跟随系统不给用户选择权”那这个方案就够了不要画蛇添足去加什么开关。但它的缺点也很明显用户没有任何自主权。很多用户希望“系统是深色但我在你这个网站想用亮色”——这种产品诉求在这个方案下完全无法满足。另外它也不适合做组件库的基础能力因为组件库的使用方往往有自己的主题策略你直接把媒体查询写死反而限制了上层应用的灵活性。3.2 方案B纯手动切换只认状态不认系统这个方案是早期网站最常做的页面里放一个亮暗切换按钮点击后给html根元素加上>:root { /* 亮色变量 */ } :root[data-themedark] { /* 暗色变量 */ }优点是把控制权完全交还给用户逻辑非常直接。缺点是它完全不理会系统偏好。用户如果在系统层面设置了深色模式进入你的网站仍然看到一片刺眼的白色这几乎是一种体验倒退。所以纯手动切换目前只适合那些“品牌视觉必须绝对统一”的特殊场景用常规产品上我基本不推荐。3.3 方案C默认跟随系统手动覆盖优先最终我采用的也是目前产品里最常见的方案是混合模式。它的行为逻辑是这样的用户从未做过任何设置时跟随操作系统偏好系统是亮色页面就亮色系统切到深色页面也跟着切用户一旦在页面里手动切换过就以手动选择为准并且把这个选择记住系统偏好后续再怎么变都不再影响已经做过手动选择的用户。你可以把它理解成一套优先级手动选择 系统偏好 默认亮色。const THEME_KEY app-theme; const media window.matchMedia((prefers-color-scheme: dark)); function getResolvedTheme(pref) { if (pref light || pref dark) return pref; return media.matches ? dark : light; } function applyTheme(pref) { const resolved getResolvedTheme(pref); document.documentElement.setAttribute(data-theme, resolved); } function saveTheme(pref) { try { localStorage.setItem(THEME_KEY, pref); } catch (e) { /* 隐私模式或禁用存储时静默失败 */ } } function currentPref() { try { return localStorage.getItem(THEME_KEY) || system; } catch (e) { return system; } } function setTheme(pref) { saveTheme(pref); applyTheme(pref); } media.addEventListener(change, () { if (currentPref() system) applyTheme(system); });这里我刻意做了一个决策把system的解析放在JS里完成而不是在CSS里写两套媒体查询。原因很简单——如果CSS里同时存在属性选择器和媒体查询两套规则暗色变量的定义就得写两遍维护成本翻倍而且出现规则冲突时分发问题的难度会直线上升。JS解析的好处是数据流永远是“偏好值 → 解析 → 写入>head script (function () { try { var stored localStorage.getItem(app-theme) || system; var dark stored dark || (stored system window.matchMedia((prefers-color-scheme: dark)).matches); document.documentElement.setAttribute(data-theme, dark ? dark : light); } catch (e) { document.documentElement.setAttribute(data-theme, light); } })(); /script link relstylesheet hrefyour-app.css /head这里有两个容易被忽略的细节。第一localStorage在隐私模式、部分浏览器禁用存储或者以本地文件方式打开时可能会抛异常所以必须用try/catch包住。一旦存储不可用就退回跟随系统系统也不可用就退回亮色。第二脚本越短越好不要在这段代码里做任何复杂逻辑它的唯一任务就是“算出当前主题并写到根元素上”其他全部都交给后面的正式逻辑。4.3 状态优先级与组件库的接口设计前面的代码把主题解析成了light或dark两种有效值但用户的偏好其实是三态的light、dark、system。在组件库里这三态最好都暴露给使用方。我的做法是把主题管理封装成一个小模块对外提供三个接口getTheme()返回当前的light/darkgetPreference()返回三态偏好setPreference(pref)负责保存并应用。组件内部只关心getTheme()的结果不需要知道用户偏好到底是什么因为主题解析对组件来说是透明的。这样设计之后业务方想加一个下拉选择器亮色/暗色/跟随系统只需要调用setPreference想在某些特殊页面强制暗色只需要临时调getTheme并在局部设置变量想埋点分析用户主题偏好分布也只需要读getPreference。接口的边界清晰逻辑不会散落一地。4.4 别忘了一个属性color-scheme很多人在做暗色模式时只盯着CSS变量却漏掉了color-scheme这个属性。它决定的是浏览器原生UI元素的渲染方式——滚动条、表单控件、下拉框选项、甚至页面默认的背景色。如果不设置color-scheme你可能会遇到这样的诡异现象页面明明是深色的但下拉列表展开后选项背景是白的滚动条还是亮色模式那根银灰色滑条地址栏和浏览器UI和页面格格不入。正确的做法是让color-scheme和当前主题同频:root { color-scheme: light; } :root[data-themedark] { color-scheme: dark; }这样浏览器会主动把原生控件渲染成深色样式滚动条、表单校验气泡这些“不属于你的代码”的部分也能跟随主题页面整体氛围才统一。这个属性我已经不只一次看到有人漏掉了它修复问题的性价比极高。5. 最容易翻车的几个坑图片、阴影、滚动条、第三方组件5.1 图片内容图、图标、背景图要分开处理暗色模式里最容易翻车的视觉元素是图片因为它不像文字和背景那样有变量可以控制。处理图片时我会按三类分开考虑。第一类是内容图比如文章配图、产品照片。这类图片本身就是内容一般不应该被强行调暗或加滤镜否则会失真。但它们在暗色背景下确实会显得“扎眼”因为图片通常是亮底。我的经验是给内容图包一层容器在暗色主题下加一个极低透明度的深色遮罩或者轻微降低亮度比如filter: brightness(0.92)既能减弱突兀感又不至于破坏图片内容。第二类是图标。如果要让图标自动跟随主题最佳实践是用内联SVG并把填充色设为currentColor这样图标颜色会自动继承文字颜色变量。如果图标是背景图或img引入的固定色SVG那就只能额外准备一套暗色图标成本高很多。第三类是背景图。很多卡片的大图背景是从设计稿里导出的带白色底图的文件切到暗色模式后白色底会像一块块补丁一样贴在深色页面上。这种问题没有CSS层面的优雅解法只能从源头解决——设计交付时把背景图导出为透明底的PNG/WebP或者在暗色模式下换一张深色背景图。5.2 阴影消失后层级怎么保住前面我说过暗色模式下黑色阴影几乎不可见但这里我想再展开两个具体的替代做法。第一个做法是用描边。给卡片加一个透明度很低的浅色描边比如border: 1px solid rgba(255,255,255,0.08)在深色背景下这条若隐若现的亮边能把卡片的边界勾勒出来视觉上非常干净。第二个做法是用“亮面层级”也就是我前面调色板小节里提到的弹层比卡片亮一档卡片比页面底色亮一档靠面与面之间的明度差异来建立层级。很多设计师在暗色模式下依然堆阴影参数调半天也不出效果就是没想明白“暗色模式下阴影本来就该让位给面层亮度”。记住这个原则之后暗色模式的层级设计会简单很多。5.3 原生控件和滚动条交给color-scheme处理这一节要补充的是color-scheme并不能覆盖所有原生控件比如表单元素的内部细节在不同浏览器里的表现仍然有差异。如果你追求像素级一致还是得自己写表单控件的样式。但有一个问题用它解决得非常干净就是滚动条。打开暗色模式后如果滚动条还是亮色的页面整体会立刻“破功”。除了color-scheme之外还可以用scrollbar-color更精确地控制滚动条颜色:root[data-themedark] { scrollbar-color: #3A3F47 transparent; scrollbar-width: thin; }scrollbar-width: thin在Windows平台上会让滚动条变细整体更贴合深色界面的视觉习惯transparent轨道让滚动条不抢视觉焦点。这里仍然建议配合color-scheme一起使用因为有些浏览器对scrollbar-color的支持是有限的color-scheme兜底。5.4 第三方组件、内联样式和iframe的边界如果你不是从零开始写所有组件这里有一个大坑第三方组件库的暗色模式支持程度参差不齐。有的组件库需要你额外引入一个暗色主题CSS文件有的组件直接在内部用了硬编码颜色你用CSS变量根本覆盖不了。在动手之前先做一次“组件库暗色模式支持度”的审计。审计内容很简单把页面切到暗色模式逐个过一遍你用到的组件看有没有颜色异常。如果第三方组件是内联样式写死的颜色那基本只能靠组件库升级或者换组件解决不要指望CSS能穿透内联样式。另外还要注意iframe。第三方嵌入的内容比如地图、视频播放器、评论框运行在独立的文档环境里你的>* { transition: all 0.2s ease; }这条规则在切换主题的那一刻确实让所有元素一起“渐变”了但代价是全身的transition会让页面里所有hover、focus动画都变得非常拖沓甚至产生性能问题因为每次hover状态变化浏览器都要对大量元素做样式插值。我自己一般是完全避开全局*的过渡只在切主题时用一小段作用域受限的规则html.theme-transitioning *, html.theme-transitioning *::before, html.theme-transitioning *::after { transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease; }在切换主题时临时给根元素加上theme-transitioning类动画结束再移除。另外尊重用户的动态效果偏好prefers-reduced-motion用户应该直接关掉过渡media (prefers-reduced-motion: reduce) { * { transition: none !important; } }6. 验收清单用这份标准判断暗色模式是否真的合格6.1 对比度验收表暗色模式做完不能“看起来差不多”就算完。我给自己定的验收标准是一张可以逐行打勾的清单第一项就是对比度。检查项最低标准说明正文文字与背景4.5:1最核心的阅读体验次要文字与背景4.5:1注释、辅助说明文字经常被忽略大号文字3:1标题、大号数据展示图标与背景3:1导航图标、工具栏图标输入框边框、控件描边3:1即使不作为文字仍要可辨识对比度的计算可以直接用在线计算工具或者写一个小脚本批量提取页面上所有前景色和背景色的组合来算。不建议凭肉眼判断暗色环境下人眼对低对比度内容的感知偏差非常大。6.2 三种切换场景完整回归暗色模式最常见的回归遗漏就是只测了“手动切换”和“跟随系统”两个场景漏掉了组合场景。我建议每次发版前至少跑这三条路径。第一条系统偏好从亮色切到深色页面上没有手动设置记录页面应该跟随变暗。第二条页面上手动把主题从亮切到暗再刷新页面应该保持暗色。第三条用户手动设为暗色后再回到系统设置里把系统切回亮色页面应当保持暗色不变——这是最容易出bug的场景因为很多实现会把系统偏好同步覆盖掉手动选择。另外还要测一个隐性的点在浏览器禁用JS的情况下页面至少应该有一个可用的默认样式。我一般会让CSS里保留纯媒体查询的兜底这样即使JS挂了系统深色用户也能看到深色页面而不是白屏一片。6.3 组件级与极端状态检查暗色模式验收不能只看主页面模板要一个组件一个组件地过。我自己排查时会把以下这些点都列出来表单控件的正常、focus、禁用态表格的斑马纹和表头底色弹层、抽屉、提示框的遮罩透明度下拉面板在展开时的背景色加载骨架屏的闪烁动画在深色下是否过亮空状态插画的底色是否还带着白色块tooltip弹出时的边框对比度。这个工作量不小但很值得。暗色模式下很多组件在亮色模式下从来没暴露过的样式瑕疵会集中跳出来比如某个组件用了硬编码的白色背景切到暗色后变成一个白色方块悬在界面上。遇到这种情况没有捷径只能把硬编码颜色全部改成语义变量。6.4 两件容易被忽略的事包体和自动化最后说两个项目层面容易被忽略的点。第一点是性能与包体。老项目如果当初是用“两套完整CSS文件”实现主题切换的比如亮色一套light.css暗色一套dark.css那么切换主题时要么全量加载两套文件要么动态加载多一份CSS都会对首屏或切换性能有影响。现在用CSS变量实现主题的边际成本几乎可以忽略这类双文件方案应该逐步淘汰。第二点是自动化检查。人工检查容易漏我建议在暗色模式做完之后至少接入一次自动化的对比度审计和一次亮暗模式的截图对比。自动对比度审计可以从页面里提取所有计算后的颜色对标注出低于阈值的组合截图对比可以用来捕捉那些“颜色没变但布局被撑开”的意外。自动化不能完全取代人工回归但能把漏检率降一个量级。暗色模式做下来我个人最大的体会是这个功能看起来是纯工程问题实际上七分是设计决策三分是代码。只要把调色板设计成语义化变量、把主题状态设计成手动优先于系统的三态模型、把防闪白脚本放到head里剩下的组件适配和视觉细节其实就是沿着这套框架一项一项填内容。如果你正在用自己的组件库或者后台系统做暗色模式建议先从设计令牌入手别急着写切换逻辑——方向对了后面每一步都会顺畅很多。 
长河君 · 2026/10/17 22:31:13 · 阅读 1.2k 暗色模式实战：语义化变量、主题切换与防闪白全攻略
做前端的时间越长我越觉得暗色模式是一个特别容易被低估的功能。表面上看它就是“把页面背景从浅色换成深色”不少人第一反应都是“这不就是加两行CSS的事吗”。可真正上手做一次你会发现从设计定位、色彩体系、状态管理到渲染时机每一环都有讲究做不好用户切过去一眼就难受。我自己在维护某内部组件库时暗色模式前后做了三轮大改才沉淀出今天这套比较顺手的流程。这个系列正好写到第6篇我借这个机会把完整思路整理出来接着前面几篇已经铺好的基础设施这次专门聊暗色模式。这篇内容对你的参考价值在于不管你是要给企业后台加一个夜间阅读模式还是做个人博客的亮暗切换又或者是在组件库里把暗色模式做成全局基础设施这套方法都可以直接落到你自己的项目里。我会按做项目的实际顺序来写——先拆目标再设计调色板然后选技术方案接着处理状态管理与防闪白最后是一份可以照抄的验收清单。文章里没有空话基本都是踩过坑之后总结出来的结论和代码。1. 先拆目标暗色模式真正要解决的是什么1.1 从用户场景反推真实需求做技术的人很容易掉进“实现细节”的坑里一上来就研究CSS变量怎么定义、JS怎么监听系统偏好。但暗色模式这个功能起点压根不在代码里而在用户场景里。用户为什么需要暗色模式我归纳下来基本是三类动因。第一类是舒适度深夜躺在床上刷手机、在光线很暗的房间里看文档纯白背景的屏幕等于一个小型手电筒瞳孔被强光反复刺激眼睛很快就酸了。第二类是省电OLED屏幕上黑色像素不发光大面积深色界面确实能降低功耗这个在移动端尤其明显。第三类是审美偏好有些用户就是觉得深色界面更专注、更“高级”哪怕在白天也会主动切过去。如果把这些场景倒推成产品需求结论就很清楚了一个合格的暗色模式不是“把页面变黑”而是让用户在深色环境下依然能像在亮色模式下一样高效地获取信息。这意味着文字的对比度、界面元素的层级感、hover和focus这类交互状态、甚至图标和图片的可辨识度全部都要重新设计一遍。它不是一次自动翻转而是一套与亮色模式平行存在的视觉方案。1.2 三个需求层次对应三种实现成本我在不同项目里接触过暗色模式的各种做法总结下来用户侧的需求大概可以分为三个层次每个层次的实现成本和产品形态差别很大。需求层次表现形态典型场景实现成本跟随系统没有手动开关操作系统切到深色页面跟着变深色内容型网站、博客、文档站低手动切换页面内提供一个开关用户自己选亮或暗选择被记住需要品牌强统一的站点、编辑部后台中自适应混合默认跟随系统用户手动切换后以手动选择为准组件库、高频使用的C端产品、工具类应用高这三个层次不是随便定的它们分别对应了不同的产品哲学。跟随系统是把决定权交给操作系统用户在你的页面上不需要做任何事手动切换是把决定权完全交给用户但用户得自己记住想要什么混合模式则是两者的综合——系统给你一个合理的默认值用户又随时可以覆盖它。1.3 动手写代码前先回答三个问题结合我自己的经验任何项目开始做暗色模式之前都应该先回答三个问题。第一目标用户会不会在深色环境下长时间使用你的界面如果产品主要使用场景是明亮办公环境暗色模式的优先级可以放很低如果是阅读类、工具类、社区类产品那暗色模式就属于基础体验不是加分项。第二产品需不需要给用户手动开关这个问题的判断依据是品牌一致性和用户控制欲。像很多内容消费产品用户就是要夜间躺着看他未必愿意去改系统设置所以应用内开关几乎是必须的。而有些品牌感极强的官网页面效果是精心调过的结论可能是“不管系统怎么变我们只提供亮色”这也是一种合理选择。第三品牌主色在深色背景下还能不能保持辨识度这个问题常被忽略。很多品牌的VI色是为了白底设计的放到深色背景上要么太亮刺眼要么饱和度失衡需要在暗色主题里专门准备一套品牌色的“暗色版本”。这三个问题直接决定了后面的技术选型。我把它写在最前面是因为见过太多项目一上来就写CSS后来发现要么缺开关要么开关做了但系统联动没做最后推倒重来。先花十分钟把目标想清楚后面省的是几天的返工时间。2. 调色板设计暗色模式的根基是一套语义化变量2.1 硬编码颜色是暗色模式的头号敌人很多老项目接入暗色模式时最头疼的问题不是技术做不到而是代码里到处散落着#fff、#333这类写死的颜色。你没法全局搜一下“白色”就替换完因为有的白色是背景有的白色是文字颜色有的白色只是某个描边的反光效果。面对这种代码暗色模式根本不是“加一套变量”能解决的你得先把所有硬编码颜色改造成变量。正确的做法是放弃以“颜色本身”命名改用以“语义”命名。所谓语义化变量就是变量名描述的是“这个颜色用什么”而不是“这个颜色是什么”。:root { --bg-canvas: #F7F8FA; /* 页面最底层背景 */ --bg-surface: #FFFFFF; /* 卡片、面板等承载内容的表面 */ --bg-overlay: rgba(0,0,0,0.55); /* 遮罩层 */ --text-primary: #1D2129; /* 正文文字 */ --text-secondary: #5B6472; /* 次要说明文字 */ --text-disabled: #9AA1AB; /* 禁用状态文字 */ --border-divider: #E6E8EB; /* 分割线、描边 */ --accent-brand: #3B82F6; /* 品牌强调色 */ --success: #16A34A; --warning: #D97706; --danger: #DC2626; }组件里只引用var(--bg-surface)、var(--text-primary)这类语义变量。亮色和暗色主题就只是这组变量在不同作用域下的两套映射关系。这样设计之后切换主题本质上只是切换一组变量的值组件代码一行都不用动。2.2 暗色模式里的层级是靠“更亮”来表达的这里需要解释一个视觉原理。在亮色模式下我们判断“这个卡片浮在页面上”主要靠的是阴影——卡片在白色背景上投下一个柔和的灰色阴影层次感就出来了。但到了暗色模式背景本身已经是深色的黑色阴影几乎不可见再用“加深阴影”的方式表达层级基本是无效的。所以暗色模式里有个反直觉的规则层级越高表面颜色反而越亮。就像在一个暗房间里离你越近的物体会被光线照得更亮离你越远的背景则隐入黑暗。应用到界面上就是页面底色最深普通卡片稍亮一点弹层和浮层最亮。层级亮色主题暗色主题说明页面底色#F7F8FA#121417最底层卡片/面板#FFFFFF#1D2024比底色亮一档弹层/浮层#FFFFFF 强阴影#262A30最高层最亮悬浮/按压态黑色遮罩4%白色遮罩6%用遮罩而非改色这个表格里的数值是我自己在实践中比较顺手的起点不是标准答案。不同产品的视觉风格不同但“层级越高越亮”这个原则是通用的。你只需要在调色板里定义三到四档表面色用的时候严格按层级取用不要在组件里自己发明新的灰色。2.3 对比度不是玄学直接按标准算暗色模式里最容易翻车的其实是次要文字。主文字用白字配深底通常没问题但很多设计会把次要说明文字调得太暗想着“深色模式嘛次要文字暗一点不打扰”结果对比度跌破可读性底线用户在夜间模式下看辅助信息简直是受刑。对比度这块直接参考可访问性领域的通行标准就行。正文文本与背景的对比度至少要达到4.5:1大号文字一般指18号或14号加粗以上和界面组件图标要求放宽到3:1。这不是“可望不可及”的要求而是一个实打实的验收入口。拿我上面给的暗色变量算一下#121417的背景配合#E4E7EC的正文文字对比度大概在12:1左右算是非常宽裕配合#9AA1AB这种次要文字对比度也能到6:1左右也合格。但如果你把次要文字调成#6B7280配深色背景可能就只剩下3:1左右了这就不适合作为正文使用。另外我特别提醒一句不要用纯黑#000配纯白#FFF。纯黑背景在OLED屏上虽然省电但黑白两极的强烈对比会产生光晕感深色环境下反而累眼睛。用带一点灰的深色比如#121417作为底色配合带一点灰的白色比如#E4E7EC作为文字视觉上会舒服很多。2.4 品牌色大面积降饱和小面积保活力品牌色在暗色模式里是一个容易被忽视的坑。很多品牌蓝、品牌红是在白色底上验证过的放到深色底上原封不动搬过去会有两种问题要么太亮一大片高饱和色块在夜间非常刺眼要么和深色背景的融合度不够显得“浮”。我的处理原则是大面积使用的品牌色比如按钮底色、导航栏背景要降低饱和度和亮度让它在深色背景下不刺眼小面积使用的品牌色比如链接文字、图标、焦点描边则保持足够的明度和饱和度因为小面积元素需要靠颜色在深色背景里跳出来。这里可以用CSS的color-mix()函数来生成暗色模式下的品牌色变体不需要在每个主题里手动抄一份十六进制色值:root[data-themedark] { --accent-brand: #60A5FA; /* 亮色模式的品牌色提亮一档 */ --accent-brand-hover: color-mix(in srgb, var(--accent-brand) 85%, #FFFFFF); --accent-brand-active: color-mix(in srgb, var(--accent-brand) 75%, #000000); }color-mix()可以把品牌色和白色或黑色按比例混合hover态亮一点、按压态暗一点这样交互状态的层次感就出来了而且品牌色换版本时暗色模式会自动跟着调整不用再手算一遍。3. 技术选型三套方案我最后选了混合模式3.1 方案A纯跟随系统只有媒体查询纯CSS方案的核心就是prefers-color-scheme媒体查询:root { /* 亮色变量 */ } media (prefers-color-scheme: dark) { :root { /* 暗色变量 */ } }这个方案的优点非常突出零JavaScript没有执行时机的问题不存在闪白实现成本最低。如果你的产品定位就是“完全跟随系统不给用户选择权”那这个方案就够了不要画蛇添足去加什么开关。但它的缺点也很明显用户没有任何自主权。很多用户希望“系统是深色但我在你这个网站想用亮色”——这种产品诉求在这个方案下完全无法满足。另外它也不适合做组件库的基础能力因为组件库的使用方往往有自己的主题策略你直接把媒体查询写死反而限制了上层应用的灵活性。3.2 方案B纯手动切换只认状态不认系统这个方案是早期网站最常做的页面里放一个亮暗切换按钮点击后给html根元素加上>:root { /* 亮色变量 */ } :root[data-themedark] { /* 暗色变量 */ }优点是把控制权完全交还给用户逻辑非常直接。缺点是它完全不理会系统偏好。用户如果在系统层面设置了深色模式进入你的网站仍然看到一片刺眼的白色这几乎是一种体验倒退。所以纯手动切换目前只适合那些“品牌视觉必须绝对统一”的特殊场景用常规产品上我基本不推荐。3.3 方案C默认跟随系统手动覆盖优先最终我采用的也是目前产品里最常见的方案是混合模式。它的行为逻辑是这样的用户从未做过任何设置时跟随操作系统偏好系统是亮色页面就亮色系统切到深色页面也跟着切用户一旦在页面里手动切换过就以手动选择为准并且把这个选择记住系统偏好后续再怎么变都不再影响已经做过手动选择的用户。你可以把它理解成一套优先级手动选择 系统偏好 默认亮色。const THEME_KEY app-theme; const media window.matchMedia((prefers-color-scheme: dark)); function getResolvedTheme(pref) { if (pref light || pref dark) return pref; return media.matches ? dark : light; } function applyTheme(pref) { const resolved getResolvedTheme(pref); document.documentElement.setAttribute(data-theme, resolved); } function saveTheme(pref) { try { localStorage.setItem(THEME_KEY, pref); } catch (e) { /* 隐私模式或禁用存储时静默失败 */ } } function currentPref() { try { return localStorage.getItem(THEME_KEY) || system; } catch (e) { return system; } } function setTheme(pref) { saveTheme(pref); applyTheme(pref); } media.addEventListener(change, () { if (currentPref() system) applyTheme(system); });这里我刻意做了一个决策把system的解析放在JS里完成而不是在CSS里写两套媒体查询。原因很简单——如果CSS里同时存在属性选择器和媒体查询两套规则暗色变量的定义就得写两遍维护成本翻倍而且出现规则冲突时分发问题的难度会直线上升。JS解析的好处是数据流永远是“偏好值 → 解析 → 写入>head script (function () { try { var stored localStorage.getItem(app-theme) || system; var dark stored dark || (stored system window.matchMedia((prefers-color-scheme: dark)).matches); document.documentElement.setAttribute(data-theme, dark ? dark : light); } catch (e) { document.documentElement.setAttribute(data-theme, light); } })(); /script link relstylesheet hrefyour-app.css /head这里有两个容易被忽略的细节。第一localStorage在隐私模式、部分浏览器禁用存储或者以本地文件方式打开时可能会抛异常所以必须用try/catch包住。一旦存储不可用就退回跟随系统系统也不可用就退回亮色。第二脚本越短越好不要在这段代码里做任何复杂逻辑它的唯一任务就是“算出当前主题并写到根元素上”其他全部都交给后面的正式逻辑。4.3 状态优先级与组件库的接口设计前面的代码把主题解析成了light或dark两种有效值但用户的偏好其实是三态的light、dark、system。在组件库里这三态最好都暴露给使用方。我的做法是把主题管理封装成一个小模块对外提供三个接口getTheme()返回当前的light/darkgetPreference()返回三态偏好setPreference(pref)负责保存并应用。组件内部只关心getTheme()的结果不需要知道用户偏好到底是什么因为主题解析对组件来说是透明的。这样设计之后业务方想加一个下拉选择器亮色/暗色/跟随系统只需要调用setPreference想在某些特殊页面强制暗色只需要临时调getTheme并在局部设置变量想埋点分析用户主题偏好分布也只需要读getPreference。接口的边界清晰逻辑不会散落一地。4.4 别忘了一个属性color-scheme很多人在做暗色模式时只盯着CSS变量却漏掉了color-scheme这个属性。它决定的是浏览器原生UI元素的渲染方式——滚动条、表单控件、下拉框选项、甚至页面默认的背景色。如果不设置color-scheme你可能会遇到这样的诡异现象页面明明是深色的但下拉列表展开后选项背景是白的滚动条还是亮色模式那根银灰色滑条地址栏和浏览器UI和页面格格不入。正确的做法是让color-scheme和当前主题同频:root { color-scheme: light; } :root[data-themedark] { color-scheme: dark; }这样浏览器会主动把原生控件渲染成深色样式滚动条、表单校验气泡这些“不属于你的代码”的部分也能跟随主题页面整体氛围才统一。这个属性我已经不只一次看到有人漏掉了它修复问题的性价比极高。5. 最容易翻车的几个坑图片、阴影、滚动条、第三方组件5.1 图片内容图、图标、背景图要分开处理暗色模式里最容易翻车的视觉元素是图片因为它不像文字和背景那样有变量可以控制。处理图片时我会按三类分开考虑。第一类是内容图比如文章配图、产品照片。这类图片本身就是内容一般不应该被强行调暗或加滤镜否则会失真。但它们在暗色背景下确实会显得“扎眼”因为图片通常是亮底。我的经验是给内容图包一层容器在暗色主题下加一个极低透明度的深色遮罩或者轻微降低亮度比如filter: brightness(0.92)既能减弱突兀感又不至于破坏图片内容。第二类是图标。如果要让图标自动跟随主题最佳实践是用内联SVG并把填充色设为currentColor这样图标颜色会自动继承文字颜色变量。如果图标是背景图或img引入的固定色SVG那就只能额外准备一套暗色图标成本高很多。第三类是背景图。很多卡片的大图背景是从设计稿里导出的带白色底图的文件切到暗色模式后白色底会像一块块补丁一样贴在深色页面上。这种问题没有CSS层面的优雅解法只能从源头解决——设计交付时把背景图导出为透明底的PNG/WebP或者在暗色模式下换一张深色背景图。5.2 阴影消失后层级怎么保住前面我说过暗色模式下黑色阴影几乎不可见但这里我想再展开两个具体的替代做法。第一个做法是用描边。给卡片加一个透明度很低的浅色描边比如border: 1px solid rgba(255,255,255,0.08)在深色背景下这条若隐若现的亮边能把卡片的边界勾勒出来视觉上非常干净。第二个做法是用“亮面层级”也就是我前面调色板小节里提到的弹层比卡片亮一档卡片比页面底色亮一档靠面与面之间的明度差异来建立层级。很多设计师在暗色模式下依然堆阴影参数调半天也不出效果就是没想明白“暗色模式下阴影本来就该让位给面层亮度”。记住这个原则之后暗色模式的层级设计会简单很多。5.3 原生控件和滚动条交给color-scheme处理这一节要补充的是color-scheme并不能覆盖所有原生控件比如表单元素的内部细节在不同浏览器里的表现仍然有差异。如果你追求像素级一致还是得自己写表单控件的样式。但有一个问题用它解决得非常干净就是滚动条。打开暗色模式后如果滚动条还是亮色的页面整体会立刻“破功”。除了color-scheme之外还可以用scrollbar-color更精确地控制滚动条颜色:root[data-themedark] { scrollbar-color: #3A3F47 transparent; scrollbar-width: thin; }scrollbar-width: thin在Windows平台上会让滚动条变细整体更贴合深色界面的视觉习惯transparent轨道让滚动条不抢视觉焦点。这里仍然建议配合color-scheme一起使用因为有些浏览器对scrollbar-color的支持是有限的color-scheme兜底。5.4 第三方组件、内联样式和iframe的边界如果你不是从零开始写所有组件这里有一个大坑第三方组件库的暗色模式支持程度参差不齐。有的组件库需要你额外引入一个暗色主题CSS文件有的组件直接在内部用了硬编码颜色你用CSS变量根本覆盖不了。在动手之前先做一次“组件库暗色模式支持度”的审计。审计内容很简单把页面切到暗色模式逐个过一遍你用到的组件看有没有颜色异常。如果第三方组件是内联样式写死的颜色那基本只能靠组件库升级或者换组件解决不要指望CSS能穿透内联样式。另外还要注意iframe。第三方嵌入的内容比如地图、视频播放器、评论框运行在独立的文档环境里你的>* { transition: all 0.2s ease; }这条规则在切换主题的那一刻确实让所有元素一起“渐变”了但代价是全身的transition会让页面里所有hover、focus动画都变得非常拖沓甚至产生性能问题因为每次hover状态变化浏览器都要对大量元素做样式插值。我自己一般是完全避开全局*的过渡只在切主题时用一小段作用域受限的规则html.theme-transitioning *, html.theme-transitioning *::before, html.theme-transitioning *::after { transition: background-color 0.2s ease, color 0.2s ease, border-color 0.2s ease; }在切换主题时临时给根元素加上theme-transitioning类动画结束再移除。另外尊重用户的动态效果偏好prefers-reduced-motion用户应该直接关掉过渡media (prefers-reduced-motion: reduce) { * { transition: none !important; } }6. 验收清单用这份标准判断暗色模式是否真的合格6.1 对比度验收表暗色模式做完不能“看起来差不多”就算完。我给自己定的验收标准是一张可以逐行打勾的清单第一项就是对比度。检查项最低标准说明正文文字与背景4.5:1最核心的阅读体验次要文字与背景4.5:1注释、辅助说明文字经常被忽略大号文字3:1标题、大号数据展示图标与背景3:1导航图标、工具栏图标输入框边框、控件描边3:1即使不作为文字仍要可辨识对比度的计算可以直接用在线计算工具或者写一个小脚本批量提取页面上所有前景色和背景色的组合来算。不建议凭肉眼判断暗色环境下人眼对低对比度内容的感知偏差非常大。6.2 三种切换场景完整回归暗色模式最常见的回归遗漏就是只测了“手动切换”和“跟随系统”两个场景漏掉了组合场景。我建议每次发版前至少跑这三条路径。第一条系统偏好从亮色切到深色页面上没有手动设置记录页面应该跟随变暗。第二条页面上手动把主题从亮切到暗再刷新页面应该保持暗色。第三条用户手动设为暗色后再回到系统设置里把系统切回亮色页面应当保持暗色不变——这是最容易出bug的场景因为很多实现会把系统偏好同步覆盖掉手动选择。另外还要测一个隐性的点在浏览器禁用JS的情况下页面至少应该有一个可用的默认样式。我一般会让CSS里保留纯媒体查询的兜底这样即使JS挂了系统深色用户也能看到深色页面而不是白屏一片。6.3 组件级与极端状态检查暗色模式验收不能只看主页面模板要一个组件一个组件地过。我自己排查时会把以下这些点都列出来表单控件的正常、focus、禁用态表格的斑马纹和表头底色弹层、抽屉、提示框的遮罩透明度下拉面板在展开时的背景色加载骨架屏的闪烁动画在深色下是否过亮空状态插画的底色是否还带着白色块tooltip弹出时的边框对比度。这个工作量不小但很值得。暗色模式下很多组件在亮色模式下从来没暴露过的样式瑕疵会集中跳出来比如某个组件用了硬编码的白色背景切到暗色后变成一个白色方块悬在界面上。遇到这种情况没有捷径只能把硬编码颜色全部改成语义变量。6.4 两件容易被忽略的事包体和自动化最后说两个项目层面容易被忽略的点。第一点是性能与包体。老项目如果当初是用“两套完整CSS文件”实现主题切换的比如亮色一套light.css暗色一套dark.css那么切换主题时要么全量加载两套文件要么动态加载多一份CSS都会对首屏或切换性能有影响。现在用CSS变量实现主题的边际成本几乎可以忽略这类双文件方案应该逐步淘汰。第二点是自动化检查。人工检查容易漏我建议在暗色模式做完之后至少接入一次自动化的对比度审计和一次亮暗模式的截图对比。自动对比度审计可以从页面里提取所有计算后的颜色对标注出低于阈值的组合截图对比可以用来捕捉那些“颜色没变但布局被撑开”的意外。自动化不能完全取代人工回归但能把漏检率降一个量级。暗色模式做下来我个人最大的体会是这个功能看起来是纯工程问题实际上七分是设计决策三分是代码。只要把调色板设计成语义化变量、把主题状态设计成手动优先于系统的三态模型、把防闪白脚本放到head里剩下的组件适配和视觉细节其实就是沿着这套框架一项一项填内容。如果你正在用自己的组件库或者后台系统做暗色模式建议先从设计令牌入手别急着写切换逻辑——方向对了后面每一步都会顺畅很多。