深色模式实现完全指南：CSS 变量、媒体查询、持久化存储
从零到一实现网站深色模式：CSS 自定义属性定义浅深配色、prefers-color-scheme 媒体查询、用户手动切换 + localStorage 持久化、避免 FOUC、图片和阴影适配、Tailwind dark: 变体、next-themes 集成、深色模式设计原则。
深色模式已不再是可选功能，而是现代网站的标配。从 Apple 的 iOS 到 Google 的 Material Design，从 Windows 11 到各大平台的原生应用，深色模式正在成为用户的首选。实现一个高质量的深色模式不仅需要简单地反转颜色，还需要考虑用户系统偏好、手动切换、深色配色的视觉舒适度、图片和阴影的适配、持久化存储等多个方面。本指南从 CSS 变量、媒体查询、用户交互、设计原则等维度，为你详细讲解如何从零到一构建一个完整、可维护、用户友好的深色模式系统。
CSS 自定义属性定义浅深配色
CSS 自定义属性（CSS Custom Properties / CSS Variables）是实现深色模式的基础。它允许你定义一套设计 Token，在浅色和深色模式下分别赋予不同的值。通过在 CSS 中使用变量，可以轻松地在两种模式间切换而无需重复代码。CSS 变量通过 --variable-name: value 定义，通过 var(--variable-name) 使用。当用户开启深色模式或系统设置为深色时，重新定义这些变量即可实现整个网站的颜色切换。一个完整的深色模式系统通常需要以下色彩 Token：背景色（页面背景、卡片背景、表单背景等多个层级）、文本色（主文本、次要文本、禁用文本等）、边框色（卡片边框、输入框边框等）、交互色（链接、按钮、悬停状态等）、反馈色（成功、错误、警告、信息等）。通过 CSS 变量集中定义这些值，可以确保整个网站的配色一致性，也便于后续的主题切换。相比于在每个类名中写死颜色值，使用变量可以大大降低维护成本和出错风险。
prefers-color-scheme 媒体查询
prefers-color-scheme 是 CSS Media Query，用于检测用户的系统偏好（浅色或深色）。大多数现代操作系统都支持这一特性，包括 macOS、Windows、iOS、Android 等。它允许网站根据用户的系统设置自动选择合适的配色方案，提供更好的用户体验。在 HTML 的 <head> 中声明支持的配色方案，告诉浏览器和用户代理你的网站支持深色模式。这个声明的作用是：告诉浏览器你的网站支持浅色和深色两种模式，允许浏览器自动调整表单元素、滚动条等原生 UI 的颜色，告诉搜索引擎和其他爬虫你支持深色模式。JavaScript 中可以检测系统是否偏好深色模式，并监听系统设置的变化。这样当用户在操作系统中改变配色方案时，网站可以立即响应。需要注意的是，prefers-color-scheme 只检测系统偏好，不会因为用户在网站上手动切换而改变。你仍然需要通过 JavaScript 和 localStorage 来实现手动切换功能。
用户手动切换与 localStorage 持久化
虽然自动遵循系统偏好很好，但许多用户希望在网站上手动切换深色模式，而不受系统设置影响。这需要 JavaScript 和 localStorage 的配合实现。基础思路是：获取当前主题（优先读取用户手动设置，否则读取系统偏好），应用主题到 DOM，切换主题时保存到 localStorage。localStorage 最佳实践包括：Key 命名应使用命名空间前缀（如 xtechtools-theme），避免与其他网站冲突。值的格式保持一致（存储 'light' 或 'dark'）。容错处理，如果 localStorage 不可用（隐私模式等），降级到系统偏好。同步多个标签页，使用 storage 事件监听其他标签的主题变化，这样用户在一个标签页切换主题时，其他标签页也会自动更新。HTML 中的切换按钮应该清晰地显示当前状态，可以用图标（太阳/月亮）或文字标签。CSS 中动态隐藏/显示相应的图标，使 UI 更加直观。整个过程应该是无缝的，切换发生时没有页面刷新或闪烁。
避免 FOUC（闪烁）
FOUC（Flash of Unstyled Content）在深色模式中常见的问题：用户打开网站时，页面先显示浅色，然后闪烁切换到深色。这严重影响用户体验，特别是在网络较慢的情况下。问题根源在于页面加载顺序：HTML 加载，浏览器应用默认样式（浅色）；CSS 加载，确认仍是浅色；JavaScript 加载并执行，才读取 localStorage 并切换到深色，出现闪烁。解决方案是在 head 中内联脚本。脚本要放在 <head> 的最前面，CSS 之前，脚本必须是同步的（内联），不能是异步或延迟加载，脚本尽可能简短，避免阻塞页面加载。这样用户一打开网站，就会立即看到正确的深色模式样式，不会闪烁。这个技巧对用户体验至关重要，因为即使只是几百毫秒的闪烁，也会让用户感觉网站反应迟缓。通过在 head 中内联脚本，可以确保样式在 DOM 渲染之前就已经应用，从而完全消除 FOUC 问题。
图片和媒体适配深色模式
图片在深色背景下可能显示不当，需要特殊处理。CSS filter 调整是简单方案，可以通过 brightness、contrast 等滤镜调整图片在深色模式下的显示效果。但对于某些图片（如 UI 截图、设计稿），使用 picture 标签选择不同图片是更好的方案，可以为每种模式提供针对性设计的版本。针对手动切换的 class 选择器则是另一种方案，可以根据根元素的 class 显示或隐藏不同版本的图片。对于 UI 截图和设计稿，使用专用深色版本效果最好，因为这些内容往往对颜色精准度要求高。对于照片和实际图片，使用 filter 调整通常就足够了。对于图表和数据可视化，使用专用深色版本能显著提升可读性和美观度。还需要考虑响应式图片的情况，srcset 属性可以根据设备像素比选择不同的图片，这与深色模式的图片适配可以结合使用。总的来说，深色模式下的图片处理应该与浅色模式一样认真对待，因为视觉体验是用户评判网站质量的重要指标。
阴影、边框、元素适配
深色模式下，许多 CSS 属性需要调整。盒阴影是最常见的问题：浅色模式的阴影（深灰色半透明）在深色背景下不可见。深色模式下应使用更浅的阴影颜色（如浅灰色或白色的低透明度），或增加阴影的透明度和扩散距离。边框颜色也需要适配。浅色模式使用浅灰色边框，深色模式应使用深灰色边框（相对于深色背景）。背景渐变同样需要调整，确保在两种模式下都有良好的视觉层级。文本阴影在浅色模式可能有微妙的阴影增加深度，但在深色模式下应移除或调整，避免影响阅读。最佳实践是用 CSS 变量定义这些属性，确保所有地方使用一致的颜色和效果。这样不仅易于维护，还能确保深色模式在整个网站上的一致性。涉及的元素包括：输入框、按钮、卡片、悬停效果、焦点环、分割线等，都应该有相应的深色模式样式。
Tailwind CSS dark: 变体集成
如果使用 Tailwind CSS，可以利用其 dark: 变体快速实现深色模式，避免手写 CSS。Tailwind 的 darkMode 配置支持两种方式：class 方式（.dark）让你通过给根元素添加 class 来控制深色模式，media 方式则让 Tailwind 自动根据 prefers-color-scheme 应用深色样式。在 HTML 中使用 dark: 变体非常简单，例如 bg-white dark:bg-slate-900 表示在浅色模式下背景为白色，深色模式下为深灰色。Tailwind 会自动生成对应的 CSS，并根据配置方式（class 或 media）应用样式。这比手写 CSS 快得多，特别是对于包含大量颜色变化的组件。CSS 变量与 Tailwind 的组合提供了最大的灵活性。用 CSS 变量定义 design token，确保一致性，用 Tailwind dark: 变体处理快速原型化和特殊情况。对于复杂的主题系统，仍建议结合两种方式使用。Tailwind 的 dark: 变体支持所有默认工具类，包括颜色、背景、边框、阴影等，可以覆盖深色模式所需的大部分场景。
next-themes 库与高级集成
对于 React 应用（特别是 Next.js），next-themes 是实现深色模式的标准库。它自动处理 FOUC、localStorage 持久化、系统偏好检测等问题，大大简化了深色模式的实现流程。安装后，只需用 ThemeProvider 包装应用，就能获得完整的主题切换功能。next-themes 的关键特性包括：自动处理 FOUC（脚本在 head 中执行，避免闪烁），持久化存储（自动使用 localStorage 保存用户偏好），系统偏好监听（自动监听 prefers-color-scheme 变化），SSR 友好（服务端渲染和静态生成都支持），多主题支持（不仅支持浅/深，还可以定义多个主题）。与 Tailwind CSS 集成时，配置 darkMode: 'class'，next-themes 会自动在 <html> 上添加 class="dark"，Tailwind 的 dark: 变体就会自动生效。这种组合是现代 React 项目的最佳实践，提供了最大的便利性和灵活性。
深色模式设计原则
实现深色模式不仅是技术问题，设计原则同样重要。首先不要使用纯黑色。纯黑色（#000000）在屏幕上对眼睛刺激大，容易导致视觉疲劳和"屏幕刺痛"。推荐的深色背景包括 #0f0f0f（深灰色，接近黑但柔和）、#1a1a1a（常见的深色选择）、#111111（略浅于纯黑）、#18181b（Tailwind 的深色系）。不同的应用场景可以选择不同深度的背景色，关键是避免纯黑。其次要提高对比度，但不要过度。深色背景下，文字应该足够亮，以满足 WCAG 无障碍标准。推荐的文字颜色包括：主文本 #f5f5f5 或 #ffffff，次要文本 #a0a0a0 或 #b0b0b0，禁用文本 #666666 或 #757575。但纯白文字（#ffffff）在深色背景上可能过于刺眼，略带蓝色的白色（如 #f0f4f8）往往更舒适。第三是适应深色背景的色彩心理。鲜红色在深色背景下可能显得刺眼，应降低饱和度。亮黄色可能太刺眼，考虑使用更柔和的黄色。蓝色通常在深色模式下效果最好。绿色应选择较亮的绿色以保证可见度。最后要保持品牌一致性，深色模式不应该是品牌的补充，而是品牌的延伸。保持字体、间距、组件设计的一致性，只改变色彩。
常见问题
什么是 FOUC？如何避免？
FOUC 是深色模式中常见的问题：用户打开网站时，页面先显示浅色模式，然后闪烁切换到深色模式。可通过在 head 中内联 JavaScript 脚本，在 DOM 加载前立即读取 localStorage 并应用样式来避免。或使用 next-themes 等库自动处理。
为什么不应该在深色模式使用纯黑色？
纯黑色在深色模式下对眼睛刺激大，长期阅读会导致视觉疲劳。推荐使用接近黑色的深灰色，如 #1a1a1a、#0f0f0f 或 #111111。这样既提供了深色模式的优势，又保护了用户眼睛。
CSS 变量和 Tailwind dark: 变体应该怎么选？
两者可以结合使用。用 CSS 变量定义设计 Token，确保一致性；用 Tailwind dark: 变体快速原型化和处理特殊情况。对于大型项目，CSS 变量加 Tailwind dark: 是最优组合。
图片在深色模式下看起来太亮或太暗怎么办？
可以用 CSS filter 调整图片显示；或为深色模式准备不同的图片版本；或使用 picture 标签根据 prefers-color-scheme 选择不同的图片。对于截图或示意图，深色模式专用版本效果最好。
深色模式下的盒阴影需要调整吗？
是的。浅色模式的阴影颜色在深色背景下可能不可见或看起来很奇怪。深色模式下应使用更浅的阴影颜色，或增加阴影的透明度和扩散距离。
localStorage key 应该怎么命名？
推荐使用描述性的命名，如 "theme" 或 "color-scheme"。避免太通用的名称以防止与其他脚本冲突。使用命名空间前缀更好，如 "xtechtools-theme"，可以避免跨 iframe 污染。