1. 主题切换不只是加个开关先搞清楚切的到底是什么深色模式这件事我刚入行的时候以为就是写个按钮点一下给body加个 class然后改改背景色和文字色就完事了。结果在一个已经迭代了大半年的中后台项目上我第一次真正栽了跟头——产品经理说支持深色模式我花了两小时做完提交测试回来的 bug 单列了十几条图表库写死的坐标轴颜色没变、ECharts 的 tooltip 还是白底、富文本编辑器里的 iframe 内容还是亮的、某个用了 third-party 组件的弹窗还是白花花的。那次之后我才意识到深色模式从来不是改颜色而是一套贯穿样式架构、状态管理、首屏渲染和第三方集成的系统工程。先把话说透所谓主题切换本质上是在运行时替换一组视觉决策变量。颜色只是最显眼的那部分真正要管的还包括阴影、边框、透明度叠加、图片滤镜、代码高亮配色甚至滚动条样式。你把这些东西统称为设计 token或者样式变量主题切换要做的就是在一个统一的入口把这套变量的取值整体换掉让所有消费这些变量的地方自动跟着变。理解这一层后面所有方案的选择都只是在回答同一个问题变量存在哪、什么时候替换、怎么让所有地方都吃到新值。1.1 颜色、变量与 token 三层关系很多同学一开始没分清这三层导致后面越写越乱这里我掰开说。最底层是原始色板palette比如#1f2430、#f5f7fa这种具体的色值它们是死的不带语义。中间层是语义变量semantic token比如--color-bg-page、--color-text-primary、--color-border-subtle。最上层是组件消费组件的样式里只写background: var(--color-bg-page)绝不写具体色值。为什么要分三层因为如果组件里直接写死色值主题切换就只能靠全局覆盖、!important硬怼最后维护成本爆炸。而有了语义层切换主题只需要替换语义变量的定义组件那一层完全不用动。这就像你家里的灯开关面板统一控制你不需要为了换成暖光灯去拆每一个灯泡。提示判断一个项目的主题方案是否健康看它组件里还有多少硬编码的#fff、#000、rgb(255,255,255)。这些数字就是未来切换主题时你要一个个手动修的坑。1.2 为什么很多项目做到一半就返工我复盘过几个失败案例返工的原因高度一致基本都是这三类色值散落在各处开发过程中图省事每个页面自己写颜色主题方案上线时发现要改几百个文件。第三方组件不听话图表、编辑器、地图、弹窗组件内部有自己的配色逻辑不读你的 CSS 变量。首屏闪烁没人管本地开发时切换很顺上线后用户一刷新先闪一下刺眼的白屏体验直接崩。前两个是架构问题第三个是渲染时序问题它们对应的是完全不同的解法。所以别急着写代码先把这几个前提确认清楚。1.3 方案选型前必须确认的四个前提我现在的习惯是动手前先过一遍这四个问题答案会直接决定我选哪套方案确认项影响是否需要跟随系统决定要不要引入prefers-color-scheme和三态逻辑是否 SSR / 首屏直出决定主题状态存 cookie 还是 localStorage以及要不要服务端拼接主题数量只有明暗两套还是未来会扩展成多品牌主题技术栈与组件库Tailwind、Element Plus、Ant Design 各自对暗色模式的支持方式不同这四个问题的答案基本能框定你的技术路线。比如一个 SSR 的官网主题状态大概率要放 cookie 让服务端读到首屏直接输出正确的 class而一个纯 CSR 的后台管理localStorage 加内联脚本就够了。2. CSS 变量 根节点 class最朴素也最抗造的一条路如果只能推荐一种方案我闭眼选CSS 自定义属性CSS Variables配合根节点 class 切换。它不依赖任何框架、不依赖构建工具、改动面小、调试直观而且天然支持运行时动态切换。我经手的大多数项目最终都收敛到这条路上包括那些一开始用了花哨方案的。2.1 运行时变量为什么比预编译变量更合适这里有个关键区分SCSS/Less 的变量是编译期的CSS 变量是运行期的。预编译变量在打包时就被替换成静态值了所以你想运行时切换只能编译出两套样式表比如theme-light.css和theme-dark.css然后动态切换link的 href或者用两套 class 包裹。这条路能走但会导致样式体积翻倍而且切换时会有一个短暂的样式加载空档。CSS 变量不一样它活在浏览器运行时document.documentElement.style.setProperty(--color-bg, #000)一执行所有引用了这个变量的元素立刻重绘。这种改一处、动全局的特性正是主题切换最想要的。2.2 一份可以直接抄的最小实现我一般会这么组织。先定义一个统一的主题属性挂在html上/* 亮色默认 */ :root { --color-bg-page: #f5f7fa; --color-bg-card: #ffffff; --color-text-primary: #1f2430; --color-text-secondary: #6b7280; --color-border-subtle: #e5e7eb; --color-shadow: 0 2px 8px rgba(0, 0, 0, 0.08); } /* 暗色 */ html[data-themedark] { --color-bg-page: #121212; --color-bg-card: #1e1e1e; --color-text-primary: #e5e7eb; --color-text-secondary: #9ca3af; --color-border-subtle: #2f333a; --color-shadow: 0 2px 8px rgba(0, 0, 0, 0.5); }注意我用的是>function applyTheme(theme) { document.documentElement.setAttribute(data-theme, theme); }组件里消费的时候永远只用语义变量.card { background: var(--color-bg-card); color: var(--color-text-primary); border: 1px solid var(--color-border-subtle); box-shadow: var(--color-shadow); }这套东西跑起来切换主题就是一次属性修改零闪烁、零加载。2.3 变量分层的组织方式与命名约定变量一多命名就成了大问题。我踩过的坑是一开始命名很随意--dark-bg、--bg2、--mainColor混着来两周后自己都不记得哪个是哪个。后来我固定了一套命名规范--{类别}-{子项}-{状态}比如背景类--color-bg-page、--color-bg-card、--color-bg-hover、--color-bg-mask文字类--color-text-primary、--color-text-secondary、--color-text-disabled、--color-text-link边框类--color-border-subtle、--color-border-strong功能色--color-success、--color-warning、--color-error、--color-info功能色在两套主题下其实可以保持相近的色相只调整亮度和饱和度保证语义一致——用户不应该因为你切了深色模式就分不清哪个按钮是确认哪个是删除。2.4 这套路线的边界在哪里CSS 变量方案不是万能的它有两个明确的边界第一老浏览器兼容性。现代浏览器对 CSS 变量支持已经很好了但如果你的项目还需要照顾非常老的 IE那这条路走不通。不过说实话2024 年之后还在要求兼容 IE 的前端项目已经很少了。第二第三方组件的穿透问题。很多组件库内部用自己的主题机制不读你的 CSS 变量。这时候你有两个选择一是利用组件库自身提供的主题配置比如 Element Plus 的暗色主题、Ant Design 的ConfigProvider二是用 CSS 变量去劫持它们的内部样式。我一般优先用官方的主题机制实在没有才硬覆盖因为硬覆盖在组件库升级时极易失效。3. 跟随系统prefers-color-scheme 和三态设计用户对深色模式最自然的预期是我系统开了深色你就该是深色。这个能力靠 CSS 媒体查询prefers-color-scheme实现但真正的难点不在能不能检测而在用户手动选择和系统设置之间的优先级。3.1 三态开关亮、暗、跟随系统成熟产品的主题设置基本都是三个选项浅色、深色、跟随系统。为什么不做成一个开关切两态因为用户可能白天用系统浅色晚上系统自动转深色他希望网页跟着变但某天他打开网页想强制用浅色看报表这时候又需要手动覆盖。三态才能同时满足这两种诉求。媒体查询本身的写法很直接media (prefers-color-scheme: dark) { :root { --color-bg-page: #121212; /* ... */ } }但如果你同时有>function resolveTheme(stored) { if (stored light || stored dark) return stored; // auto 或不存时跟随系统 const mq window.matchMedia((prefers-color-scheme: dark)); return mq.matches ? dark : light; }解析出来的结果才写到>const mq window.matchMedia((prefers-color-scheme: dark)); mq.addEventListener(change, (e) { if (getStoredTheme() auto) { applyTheme(e.matches ? dark : light); } });这里有两个容易忽略的点。第一只在auto状态下响应变化用户显式选了浅色就不能被系统带跑。第二addEventListener在很老的浏览器上要用addListener虽然现在基本不用管了但如果项目要兼容旧环境记得做兜底。注意不要在每次渲染或组件重新挂载时都注册一遍监听会造成内存泄漏和重复触发。注册一次挂在应用根级别就好。4. 把主题搬进构建工具SCSS、Tailwind、CSS-in-JS 各自的门道同样是做深色模式不同的技术栈有不同的官方姿势。这一节我把常见的几类横向拆开讲重点说清楚它们各自的机制和坑在哪而不是简单罗列。4.1 SCSS 变量做主题为什么会翻车这是我见过最多的误区。很多同学写了$bg-color: #fff;然后想那我定义两套 SCSS 变量不就完了。问题在于SCSS 变量是编译期确定的运行时根本改不了。于是有人想出一招把两套主题都编译出来用 class 包裹。.theme-light { --bg: #fff; } .theme-dark { --bg: #000; }这么做其实绕了个弯——你最终还是落到了 CSS 变量上。所以我的建议很直接SCSS 用来做嵌套、mixin、函数这些工程化能力但主题色一定要输出成 CSS 变量。两套体系不要混着用。4.2 Tailwind darkMode 两种模式的区别Tailwind 的深色模式有两种配置// tailwind.config.js module.exports { darkMode: media, // 或 class };media模式直接用prefers-color-scheme好处是零 JS坏处是无法让用户手动覆盖。class模式会生成基于祖先 class 的变体.dark .bg-white配合手动切换 class 使用这也是我现在默认选的模式。用class模式时切换就是给html加或移除darkclassdocument.documentElement.classList.toggle(dark, isDark);Tailwind 的暗色变体写法很直观div classbg-white dark:bg-gray-900 text-black dark:text-white。它的问题是当组件多起来之后每个元素都要写两份类名可读性会下降。所以 Tailwind 项目里我更推荐结合 CSS 变量——定义好语义变量然后用 Tailwind 引用变量通过theme.extend.colors配置减少双写。4.3 CSS-in-JS 的 ThemeProvider 路线styled-components、emotion 这类方案提供了ThemeProvider天生就是为多主题设计的const theme { light: { bg: #fff, text: #000 }, dark: { bg: #000, text: #fff }, }; ThemeProvider theme{current dark ? theme.dark : theme.light} App / /ThemeProvider组件里通过props.theme.bg消费。它的优点是类型安全配合 TypeScript 体验很好、主题对象清晰。缺点也很现实运行时会有额外的计算开销SSR 场景下需要处理样式提取和 hydration 一致性问题而且它和 CSS 变量体系是两套逻辑如果项目里既用 emotion 又用普通 CSS容易割裂。我的经验是纯 CSS-in-JS 的项目用 ThemeProvider 很舒服混合栈的项目还是统一走 CSS 变量更省心。4.4 四种方案横向对比我把几种主流方案摊开对比如下方便你按项目情况选方案运行时切换首屏闪烁风险多主题扩展适合场景CSS 变量 根节点属性支持低可脚本预处理好绝大多数项目SCSS 变量切 class间接支持中一般老项目改造Tailwind darkMode支持中一般Tailwind 技术栈CSS-in-JS ThemeProvider支持中需处理 SSR好纯 CSS-in-JS 项目选型的核心逻辑其实就一句话优先选能集中管理变量、运行时切换成本低、且和首屏渲染时序好配合的方案。按这个标准CSS 变量几乎是全能选手。5. 首屏闪一下白FOUC 的根因与阻塞脚本的写法前面聊的都是切换后好不好看但用户感知最强的其实是首屏那一下闪烁。我见过太多本地开发一切正常、上线就被吐槽打开先闪一下白的项目。这一节单独拆开讲因为它是纯 CSR 和 SSR 项目都绕不过去的坎。5.1 闪烁到底发生在那几个毫秒里时序是这样的浏览器先解析 HTML、加载并应用 CSS此时因为还没执行到你的主题脚本页面按默认主题通常是亮色渲染然后 JS 加载执行读到存储里的dark改成深色。这一前一后用户就看到了从白到黑的跳变。关键点在于CSS 一旦应用就会立刻绘制而你的主题脚本往往排在很后面。只要主题脚本的执行晚于首屏绘制闪烁就必然发生。解决办法是让主题脚本尽可能早地执行——早到在首屏绘制之前。5.2 head 里内联阻塞脚本的写法正确做法是把主题判断逻辑内联写进head放在所有样式表之前或紧随其后head script (function () { try { var stored localStorage.getItem(theme); var theme stored || auto; if (theme auto) { theme window.matchMedia((prefers-color-scheme: dark)).matches ? dark : light; } document.documentElement.setAttribute(data-theme, theme); } catch (e) { document.documentElement.setAttribute(data-theme, light); } })(); /script link relstylesheet href/main.css / /head这段脚本很短但几个细节都别省必须是内联的不能是外链script src因为外链要发起网络请求就来不及了。包一层 try/catch因为某些隐私模式下localStorage访问会直接抛异常。放在 head 顶部越早越好保证在样式生效和首屏绘制之前执行。这么写的效果是浏览器解析到这段脚本时就同步把>// 服务端读取 cookie const theme req.cookies.theme || light;然后模板里直接输出html>window.addEventListener(storage, (e) { if (e.key theme) { applyTheme(resolveTheme(e.newValue)); } });storage事件只在其他标签页修改存储时触发当前页改不会触发自己正好适合做跨页同步。如果用的是 cookie就没这么方便的事件通常要靠轮询或者干脆不处理——大部分产品的做法是各页各自读初始值也能接受。6.3 从明暗两套扩展成多主题如果哪天产品说我们还要加一套品牌蓝主题你的方案扛不扛得住扛得住的前提就是前面强调的所有颜色都走语义变量。扩展时只需要新增一组变量定义html[data-themebrand-blue] { --color-bg-page: #eef4ff; --color-bg-card: #ffffff; /* ... */ }组件一行都不用改。这也是为什么我一直坚持组件只碰语义变量这条铁律——它不是洁癖而是给未来留活路。7. 收尾前的几件小事过渡动画、图片适配、可访问性与测试大框架搭好之后还有几个细节决定成品是能用还是好用。这些点很碎但每一个都会直接影响观感我挑几个高频的讲。7.1 切换过渡动画要不要加切换瞬间颜色突变会比较生硬加一个过渡会舒服很多:root { transition: background-color 0.25s ease, color 0.25s ease; }但这里有个坑过渡不要加在*上否则首次加载时所有元素一起做动画性能会很差页面看起来像渐变入场。我的做法是只在根节点和少数大块容器上加过渡或者切换时临时加一个 class、切完再移除避免影响首屏。更稳妥的方案是用一个短暂的过渡开关document.documentElement.classList.add(theme-transition); applyTheme(next); setTimeout(() { document.documentElement.classList.remove(theme-transition); }, 300);.theme-transition, .theme-transition * { transition: background-color 0.25s ease, color 0.25s ease !important; }这样只有切换那一刻才有动画首屏不参与。7.2 图片和插画在深色下的表现纯色和文字靠变量能搞定但图片是另一回事。白底插画丢进深色页面会亮得刺眼。常见处理有几类一是给插画准备两套资源按主题切换二是对图片加轻微滤镜filter: brightness(0.85)三是用带透明通道的 SVG让它跟随当前文字色渲染fill: currentColor。我一般优先推 SVG 方案因为它天然适配主题体积也小。7.3 可访问性对比度不能想当然深色模式下最容易翻车的是对比度不足。浅灰文字放在深灰背景上看起来高级但可能根本不达标。正文文字和背景的对比度建议不低于 4.5:1大字号标题可以放宽到 3:1。这个数值不是拍脑袋是 WCAG 的通行标准用在线对比度检查工具过一遍很快。另外深色模式下不要用纯黑#000配纯白#fff对比过强反而刺眼我一般用#121212到#1e1e1e这档深灰做背景。7.4 怎么测才靠谱测试这块我总结了一个清单基本能覆盖大部分问题测试项关注点首屏刷新有无白/黑闪烁弱网下是否更明显三态切换亮、暗、跟随系统之间来回切是否正确系统联动系统改主题页面在 auto 下是否跟随跨标签页多标签同步是否正常第三方组件图表、编辑器、弹窗是否都变了对比度文字、图标、边框是否都看得清存储异常隐私模式下是否还能用我实测下来最容易被漏掉的是第三方组件和存储异常两项尤其是引入图表库的项目几乎每次都要单独处理一遍坐标轴、网格线、tooltip 的颜色。我个人在实际操作中的体会是深色模式这件事难的不是把颜色变暗而是把所有视觉元素都纳入一套统一、可切换的变量体系。前期花两小时定好命名规范和分层结构能省掉后面几天的返工。真正省事的项目都是那些从一开始就把颜色当变量而不是常量来写的项目。如果现在手上正有一个没做主题的老项目我的建议是从 CSS 变量分层入手先统一背景和文字这两类最显眼的 token跑通一条完整的切换链路再逐步把边框、阴影、功能色补上去——一口吃不成胖子但方向对了后面会越来越顺。