暗色模式图像实现指南 - 使用 picture 元素和 CSS 进行切换

暗色模式与图像挑战 - 为什么需要图像适配

暗色模式已成为现代 Web 设计的标配。然而，简单地切换背景色和文字色并不够 - 图像在暗色背景上的表现往往需要特别处理。白色背景的截图在暗色界面中显得刺眼，浅色图表在深色背景上对比度不足，带有白色边缘的 PNG 图标与暗色背景产生明显的违和感。

需要图像适配的典型场景：带白色背景的产品图片、UI 截图和教程图片、图表和信息图、带透明背景但颜色不适合暗色模式的图标、以及包含文字的装饰性图像。

解决方案的选择取决于图像类型：位图图像（照片、截图）通常需要准备两套版本；SVG 和图标可以通过 CSS 动态调整颜色；而某些图像只需要调整亮度或添加边框就能在两种模式下正常显示。

需要注意的是，JPEG 与 WebP 这类位图不会随主题自动变化，纯白背景的插图或截图在暗色界面里会像发光的方块一样刺眼。

使用 picture 元素切换图像 - 纯 HTML 实现

<picture> 元素的 <source> 标签支持 media 属性，可以根据用户的颜色方案偏好加载不同的图像文件。这是最可靠的方法，不依赖 JavaScript。

基本用法：<picture><source srcset="diagram-dark.png" media="(prefers-color-scheme: dark)"><img src="diagram-light.png" alt="架构图"></picture>

这种方法的优势：浏览器只下载匹配当前模式的图像（节省带宽）、不需要 JavaScript、支持所有现代浏览器、可以与 srcset/sizes 结合实现响应式 + 暗色模式的双重适配。

与响应式图像结合：可以在每个 <source> 中同时指定 media（颜色方案）和 srcset（分辨率），实现根据设备像素比和颜色模式同时选择最佳图像。

注意事项：需要为每张图像准备两个版本，增加了资源管理的复杂度。对于大量图像的网站，应建立自动化的暗色版本生成流程。

响应式与暗色模式可以叠加使用：在 <source> 上同时写出 srcset="hero-dark-800.webp 800w, hero-dark-1600.webp 1600w"、media="(prefers-color-scheme: dark)" 与 type="image/webp"，浅色 (light) 一侧则准备 hero-light-800.webp 与 hero-light-1600.webp，末尾的 <img> 以 src="hero-light-800.jpg" 兜底并用 sizes="100vw" 告知布局宽度。把格式切换 (WebP/AVIF) 与主题切换同时进行会让 <source> 的数量增多，但浏览器只下载最先匹配的那一个来源，因此不会拖累性能。

CSS 暗色模式图像适配 - 使用滤镜和变量

CSS 提供了多种无需准备额外图像文件即可适配暗色模式的方法。

亮度和对比度调整：对于照片类图像，在暗色模式下略微降低亮度可以减少刺眼感：@media (prefers-color-scheme: dark) { img { filter: brightness(0.85); } }

反色滤镜：对于黑白图表或线条图，完全反转颜色效果很好：.diagram { filter: invert(1) hue-rotate(180deg); }。hue-rotate(180deg) 修正反色后的色相偏移，使彩色元素保持原有色调。

背景图像切换：使用 CSS 自定义属性切换背景图像 URL：:root { --hero-bg: url('hero-light.jpg'); }，在暗色模式中覆盖为暗色版本。

mix-blend-mode：对于叠加在背景上的装饰性图像，mix-blend-mode: difference 或 multiply 可以让图像自动适应背景色变化。

CSS 方法的局限性：滤镜会影响图像中的所有颜色，可能产生不自然的效果。对于需要精确控制的场景（如品牌色不能改变），仍需准备独立的暗色版本。

纯 CSS 的做法是在 @media (prefers-color-scheme: dark) 内对截图施加 filter: brightness(0.8) contrast(1.1)，压低亮度并补回对比 (contrast)；对线条图解则用 filter: invert(1) hue-rotate(180deg) 先反转再校正色相。徽标这类需要整张换图的素材可以交给变量：:root 中定义 --logo-url: url('/images/logo-light.svg')，暗色模式下改为 url('/images/logo-dark.svg')，元素侧只写 .logo { background-image: var(--logo-url); }。此外 mix-blend-mode: difference 或 exclusion 能让图像与背景做混合运算。

另一种轻量手法是把图像的不透明度降到 80-90%：以 img:not(.no-dim) { opacity: 0.85; } 统一压暗，再用 img:not(.no-dim):hover { opacity: 1; } 在悬停 (hover) 时恢复原样；不希望被压暗的图像加上 no-dim 类即可豁免。

SVG 暗色模式适配 - 使用 currentColor 动态变色

SVG 是暗色模式适配最灵活的图像格式，因为其颜色可以通过 CSS 完全控制。

currentColor 关键字：将 SVG 的 fill 或 stroke 设置为 currentColor，SVG 会自动继承父元素的文字颜色。当暗色模式切换文字颜色时，SVG 图标自动跟随变化。

CSS 变量在 SVG 中的使用：内联 SVG 可以直接使用 CSS 自定义属性：<circle fill="var(--color-primary)" />。暗色模式切换变量值时，SVG 颜色自动更新。

外部 SVG 文件的处理：通过 <img> 引用的外部 SVG 无法被 CSS 样式化。解决方案：使用内联 SVG、通过 <use> 引用 SVG sprite、或使用 CSS mask-image 将 SVG 作为遮罩并用背景色填充。

mask-image 技巧：.icon { mask-image: url('icon.svg'); background-color: currentColor; }。这样 SVG 的形状作为遮罩，颜色完全由 CSS 控制，完美支持暗色模式切换。

单色图标最省事的写法是把填充色交给 currentColor：<svg viewBox="0 0 24 24"><path fill="currentColor" d="M12 2L2 7l10 5 10-5-10-5z"/></svg> 会继承祖先元素在 CSS 中的 color 属性，因此暗色模式下文字色一变，图标也随之变色。

多色 SVG 则改用变量：图形侧写成 <rect fill="var(--svg-bg, #ffffff)" /> 与 <text fill="var(--svg-text, #333333)">Label</text>，样式侧在 :root 定义 --svg-bg: #ffffff; --svg-text: #333333;，暗色模式下覆盖为 --svg-bg: #1a1a2e; --svg-text: #e0e0e0;。SVG 文件内部也可以直接嵌入 <style> 元素写媒体查询，这样即使作为独立文件被引用也能自行切换——网站图标的 SVG 版 (favicon.svg) 尤其适合这一技巧。

截图和图表 - 实用的暗色模式工作流

技术文档和教程中大量使用的截图和图表是暗色模式适配的重点难题。

截图处理策略：最佳方案是在截图时就准备两个版本（在亮色和暗色系统设置下分别截图）。如果只有亮色版本，可以添加圆角边框和轻微阴影使其在暗色背景上不那么突兀：.screenshot { border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.3); }

图表适配：使用 CSS 变量定义图表颜色，暗色模式时自动切换。对于使用 Chart.js 或 D3.js 等库生成的图表，监听 prefers-color-scheme 变化并重新渲染。对于静态图表图像，准备两个版本或使用 CSS 反色滤镜。

代码截图：代码高亮通常已有亮色和暗色主题。确保代码块的背景色和文字色都跟随系统主题切换。使用 CSS 变量定义代码块的配色方案。

自动化工作流：对于大量截图的文档站点，建立自动化流程：使用 Puppeteer 在两种模式下自动截图、使用 ImageMagick 批量为截图添加边框和阴影、构建时根据文件命名约定（如 *-dark.png）自动生成 picture 元素。

省力的方案是只准备浅色模式的截图，再以 filter: brightness(0.8) 压暗后用于暗色界面。用 Mermaid、Draw.io、Figma 等工具绘制图解时，则可以事先定义暗色专用的配色主题，从同一份源文件导出两套成品。若想彻底自动化，可借助 Playwright 或 Puppeteer 的 page.emulateMediaFeatures 模拟暗色模式并自动截图，把它接入 CI/CD 流水线后，文档更新时两个版本就会自动重新生成。

性能与无障碍注意事项

暗色模式图像适配不应以牺牲性能或无障碍性为代价。

性能优化：

• 使用 <picture> 元素确保浏览器只下载当前模式需要的图像，避免预加载两套图像
• 对于 CSS 滤镜方案，filter 属性会触发合成层创建，大量使用可能影响滚动性能。对非视口内的图像使用 content-visibility: auto 延迟渲染
• SVG 内联会增加 HTML 文档大小。对于重复使用的图标，使用 SVG sprite + <use> 减少重复代码

无障碍考虑：

• 确保两种模式下图像的 alt 文本都准确描述内容
• 不要仅依赖颜色传达信息 - 图表应同时使用形状、图案或标签
• 暗色模式下的图像对比度同样需要满足 WCAG 标准
• 提供手动切换暗色模式的选项，不要仅依赖系统设置

过渡动画：模式切换时为图像添加平滑过渡：img { transition: filter 0.3s ease; }。避免突兀的颜色跳变影响用户体验。但注意尊重 prefers-reduced-motion 设置。

性能方面，用 CSS 的 background-image 切换时同样只会下载当前模式实际使用的图像，未命中的一侧不产生流量；但准备两套图会让存储占用翻倍，需要把 CDN 的存储成本一并计入。filter 属性由 GPU 处理，对大量图像同时套用会增加移动设备的耗电。无障碍方面，暗色模式下也要维持 WCAG AA 基准 (4.5:1) 的对比度，alt 文本应传达与浅色模式相同的内容，并一并考虑 prefers-reduced-motion。验证时可用 Chrome DevTools 的 Rendering 面板模拟 prefers-color-scheme，并建议在两种模式下分别运行 Lighthouse 的无障碍审计。