企业官网建设流程全解析

做前端这些年，几乎每个项目都会遇到深色模式的需求，但很多人对它的理解就停在“把背景改黑、文字改白”这一步。实际上，深色模式背后是CSS媒体查询、主题令牌和运行时切换机制三者拧在一起的一件事，处理不好就会遇到样式闪烁、组件适配混乱、系统设置与手动设置互相打架等各种问题。这篇文章我想把这些年做主题切换踩过的坑、沉淀下来的方案一次性说清楚，适合那些已经写过基础深色模式、想进一步把方案做扎实的同学参考。

1. 重新理解深色模式：它不是简单的颜色反转

1.1 用户需要深色模式的真实原因

很多人以为深色模式只是“好看”“酷”，但实际需求来自几个非常具体的场景。夜间使用手机或电脑时，高亮度的白色背景在暗光环境下会刺激眼睛，瞳孔在亮暗对比中反复调节，时间一长就是干涩和疲劳。OLED屏幕的深色模式还有一个硬件层面的好处：显示纯黑像素时子像素可以完全熄灭，比浅色界面省电不少，尤其对长时间刷信息流的人来说，这个差值能明显反映在电量曲线里。

但这不代表“把所有颜色取反”就完事。深色界面里如果大面积使用纯黑#000，反而容易因为对比度过高产生眩光，尤其在环境光很暗的时候，白字纯黑底的组合看久了会有一种刺眼感。业内更推荐使用类似#121212这样的深灰作为背景，配合降低饱和度的前景色，既能保持层级感又不会太生硬。真正专业的深色模式，是对色彩亮度、饱和度、边框阴影整套体系的重塑。

1.2 深色模式为什么比想象中复杂

浅色模式下，设计师可以靠阴影表达卡片层级；深色模式下阴影几乎失效，只能靠背景色明度差和边框来区分层级。侧边栏、浮层、弹窗、禁用态、链接色这些元素在深浅两套背景下，往往要有完全不同的语义映射。而且很多组件库默认只针对浅色设计，到了深色就出现对比度不足、边框透明度奇怪、阴影太脏的问题。

我见过最典型的一个案例：某个后台项目用第三方时间选择器组件，浅色模式下完全正常，切到深色模式后弹窗背景是深色，但弹窗内的按钮还是浅色模式下那种白底灰字，几乎看不清楚。这不是组件库的bug，而是我们没有在主题切换层面给第三方组件做一层适配。这个问题后面会专门展开讲。所以在动手写代码之前，先把“深色模式是完整的主题体系”这个认知立住，后面所有设计决策都会顺利很多。

2. prefers-color-scheme 媒体查询：它能做什么，不能做什么

2.1 媒体查询的本质与取值

CSS媒体查询里的prefers-color-scheme是我们做深色模式的起点，它用来检测用户系统层面的配色偏好。最基础的三段式写法是：

:root { --bg: #f5f5f7; --text: #1d1d1f; } @media (prefers-color-scheme: dark) { :root { --bg: #1d1d1f; --text: #f5f5f7; } }

注意这里prefers-color-scheme可以取light、dark，同样存在no-preference，但实际生产环境里极少单独处理no-preference，因为几乎所有操作系统和浏览器都有明确的明暗设置，它通常被当作默认的浅色样式处理。

这里有个很关键的点：这个媒体查询监听的是“系统偏好”，而不是浏览器地址栏的什么开关。用户在macOS的“外观”里选了深色，在Windows的“颜色”里选了深色，Chrome、Safari、Edge都会认为用户偏好dark。但它跟浏览器自身的主题设置（比如Chrome的深色外观）不完全是一回事，不同浏览器对这个媒体特性的响应策略有些差异，好在主流浏览器现在都能正确映射系统级偏好。

2.2 color-scheme 属性与原生控件适配

很多同学写了大量CSS变量，却忘了处理浏览器原生控件的颜色。比如滚动条、表单的日期选择器、下拉框箭头，这些元素在深色模式下默认还是浅色的，看着非常突兀。解决方案是同时声明color-scheme属性：

:root { color-scheme: light dark; } @media (prefers-color-scheme: dark) { :root { color-scheme: dark; } }

声明color-scheme: light dark的意图是告诉浏览器：“我这个页面两种模式都能支持，如果用户系统是深色，请把原生控件的配色自动切到深色方案。”这样即使我们没有专门给滚动条写样式，滚动条也会跟随系统变成深色。这个属性配合background-color一起使用，效果比单独改CSS变量更彻底。

顺便提一句，移动端HTML里的theme-color标签也很值得关注。Android Chrome会把地址栏背景色按照这个标签的值渲染，如果不做适配，深色模式下地址栏会刺眼地白着。可以在meta标签里配合媒体查询动态修改：

<meta name="theme-color" content="#f5f5f7" media="(prefers-color-scheme: light)"> <meta name="theme-color" content="#1d1d1f" media="(prefers-color-scheme: dark)">

这个细节很容易被忽略，但用户对“浏览器地址栏突然变白”的感知非常敏感，改掉之后整体感会好很多。

2.3 媒体查询的边界：它只感知系统，管不到用户手动切换

媒体查询最大的局限在于：它只能“跟随系统”，做不到“用户手动覆盖”。很多站点会提供“浅色/深色/跟随系统”三档按钮，让用户自己在站点内选择。这时如果你只写@media (prefers-color-scheme: dark)，那无论用户怎么点按钮，样式都只跟着系统走，手动选择完全失效。

所以正规的主题切换架构不会只用媒体查询，而是把媒体查询作为“跟随系统”模式下的信号源，再结合自定义属性的覆盖机制来提供手动切换。这也是下面第三部分要讲的主题令牌体系的由来。换句话说，媒体查询是地基，但真正撑起架构的是CSS变量和选择器策略。

3. 主题令牌：把颜色做成语义化变量的关键设计

3.1 从硬编码色值到语义化令牌

做主题切换如果只是把CSS里的颜色值替换掉，项目规模一大就会变成灾难。比如一百个文件里写了几百次#333，有些是文字颜色，有些是边框颜色，有些是图标颜色，你根本没法一键替换成“深色模式下的文字色”。所以我一直强调要建立“语义化令牌”。

语义化令牌的意思是不直接用“#333”这种色值，而是给它一个名字，比如--color-text-primary表示主要文字颜色，--color-bg-page表示页面背景色。组件里永远不写具体色值，只引用这些CSS变量。这样当需要切换主题时，只需要在不同作用域下给同一批变量赋不同的值即可。

3.2 构件一套完整的令牌体系

一套基础的主题令牌通常包含几个类别：背景色、文字色、边框色、品牌色、状态色（成功/警告/错误）、中性灰阶。我习惯的做法是先把设计稿里的色板抽成原始色板，再映射到语义层：

:root, :root[data-theme="light"] { --color-bg-page: #ffffff; --color-bg-elevated: #f7f7f8; --color-bg-overlay: rgba(0, 0, 0, 0.45); --color-text-primary: #1f2329; --color-text-secondary: #606770; --color-border-default: #e4e6eb; --color-brand: #3370ff; --color-success: #2e7d32; --color-warning: #b26a00; --color-error: #c62828; } [data-theme="dark"] { --color-bg-page: #181a1b; --color-bg-elevated: #242627; --color-bg-overlay: rgba(0, 0, 0, 0.6); --color-text-primary: #e8e6e3; --color-text-secondary: #b0aca8; --color-border-default: #3a3c3d; --color-brand: #5588ff; --color-success: #66bb6a; --color-warning: #ffb74d; --color-error: #ef5350; }

注意两个细节。第一，我没有在:root里同时写两套，而是用[data-theme="light"]作为显式的浅色作用域，这样无论HTML根元素有没有>.btn { background-color: var(--color-bg-elevated); color: var(--color-text-primary); border: 1px solid var(--color-border-default); } .btn--primary { background-color: var(--color-brand); color: #ffffff; }

组件完全不知道自己在浅色还是深色环境里，它只需要忠实引用变量。主题切换时只需要改>@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --color-bg-page: #181a1b; /* ... */ } }

这里:not([data-theme="light"])的写法是为了让“用户手动选了浅色”优先于“系统深色”。这种方案在纯静态页面里非常实用，不需要JS参与；但如果要做三档切换并持久化用户选择，最终还是要把><head> <script> (function () { try { var stored = localStorage.getItem('site-theme'); var darkQuery = window.matchMedia('(prefers-color-scheme: dark)'); var theme = stored || (darkQuery.matches ? 'dark' : 'light'); document.documentElement.setAttribute('data-theme', theme); } catch (e) { // localStorage不可用时兜底 } })(); </script> <link rel="stylesheet" href="/styles.css"> </head>

这个脚本必须短小、同步、无依赖。不要把它写成异步加载的外部文件，否则还是会出现闪烁。也不要在这里做过于复杂的逻辑，读取一个值、判断一个条件、设置一个属性，三行能做完的事就不要写十行。

4.2 localStorage 与三档状态管理

用户手动切换主题之后，>const ThemeManager = { current: 'system', // 用户选择 init() { const stored = localStorage.getItem('site-theme'); if (stored === 'light' || stored === 'dark' || stored === 'system') { this.current = stored; } else { this.current = 'system'; } this.apply(); }, apply() { const resolved = this.current === 'system' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : this.current; document.documentElement.setAttribute('data-theme', resolved); this.current === 'system' ? document.documentElement.removeAttribute('data-user-theme') : document.documentElement.setAttribute('data-user-theme', this.current); localStorage.setItem('site-theme', this.current); }, set(theme) { this.current = theme; this.apply(); }, listenSystemChange(callback) { const query = window.matchMedia('(prefers-color-scheme: dark)'); const handler = (e) => { if (this.current === 'system') { this.apply(); } if (callback) callback(e); }; query.addEventListener('change', handler); return () => query.removeEventListener('change', handler); } };

这里有个细节，我给根元素同时设置了>const darkQuery = window.matchMedia('(prefers-color-scheme: dark)'); if (darkQuery.addEventListener) { darkQuery.addEventListener('change', handler); } else if (darkQuery.addListener) { darkQuery.addListener(handler); }

处理函数里的逻辑很简单：只在current === 'system'时重新apply()。如果用户已经手动选择了深色或浅色，系统变化不应该影响页面当前状态，但可以在某个角落提示“系统主题已切换，是否跟随”之类的交互，这个看产品需求。

还有一个容易被忽略的点：系统主题的change事件在“跟随系统”模式下触发时机其实可能略有延迟，尤其是在跨操作系统和浏览器组合下。所以apply()里读取darkQuery.matches时最好再确认一次，不要缓存过期的值。

5. 实战排障：闪烁、第三方组件适配与调试技巧

5.1 样式闪烁（FOUC）的完整排查链路

如果内联脚本已经加了，但还是出现闪烁，通常不是脚本的问题，而是CSS变量定义顺序的问题。比如有些同事会在组件样式里直接写color: #333，这个硬编码值不会跟随变量切换，深色模式下就会出现某些文字特别亮、某些文字特别暗的现象。排查这类问题时，我会在浏览器控制台执行：

getComputedStyle(document.documentElement).getPropertyValue('--color-text-primary')

先确认根元素上变量值是否正确，再检查闪烁元素的样式是引用变量还是硬编码色值。如果变量正确但元素不对，那一定是有地方写了独立色值。全局搜索十六进制色值，一个个换成变量引用即可。

另一种闪烁发生在页面首次加载时因为背景色未设置导致白色默认底色透出。即便>html { background-color: var(--color-bg-page); }

这样无论页面内容多高、滚动条怎么拉，背景都是主题对应的颜色，不会出现露白。

5.2 第三方组件与内联样式的适配策略

第三方组件是深色模式的重灾区。它们通常把颜色写死在组件内部的CSS里，且样式优先级非常高，你很难用普通的选择器去覆盖。面对这种情况，我总结过三个层次的方案。

第一层：优先调整CSS变量。很多现代组件库（包括一些开源UI库）都支持通过CSS变量定制主题，搜一下文档里的“dark mode”或“CSS Variables”，把对应的变量映射到我们的语义令牌上。这是最干净、最可持续的方式。

第二层：用[data-theme="dark"]加高优先级选择器覆盖。比如某个组件用了一个特别深的背景，我们在外层这么写：

[data-theme="dark"] .third-party-modal .modal-footer { background-color: var(--color-bg-elevated); border-top-color: var(--color-border-default); }

由于我们给根元素加了><picture> <source srcset="hero-dark.png" media="(prefers-color-scheme: dark)"> <img src="hero-light.png" alt="banner"> </picture>

但需要注意，这里用的是媒体查询，和用户在站点内手动选择的主题可能不一致。如果站点支持手动切换，需要把“当前解析主题”也同步给图片逻辑，或者直接用CSS滤镜做简单适配。最省事的办法是把图片作为CSS背景图，并放在不同>