HTML中如何设置暗色模式支持

本文详解如何利用 CSS 原生媒体查询 `@media (prefers-color-scheme)` 为网页无缝接入系统级暗色模式支持——无需 JavaScript，仅通过标准 CSS 即可自动响应 macOS、Windows 或 iOS 的系统主题设置；强调必须使用完整语法（如 `@media (prefers-color-scheme: dark)`），并推荐采用“默认亮色 + 暗色覆盖”的稳健写法，有效规避回退异常与白屏风险，是构建现代响应式、无障碍 Web 界面的必备实践。

如何用 @media (prefers-color-scheme) 检测系统主题

浏览器原生支持，无需 JS，直接在 CSS 里写媒体查询就能响应系统暗色/亮色设置。关键点是它只读取操作系统级偏好（macOS 系统设置、Windows 设置 → 个性化 → 颜色、iOS 设置 → 显示与亮度），不读取浏览器自身主题或插件开关。

• 必须用 @media (prefers-color-scheme: dark) 或 @media (prefers-color-scheme: light)，不能写成 prefers-dark-mode 或漏掉括号
• 未匹配时会回退到常规样式，所以推荐「默认写亮色样式，再用 @media 覆盖暗色」，避免漏写导致白屏或反色异常
• 部分旧版 Safari（@supports (prefers-color-scheme: dark) 做安全包裹，但注意 @supports 本身在 Safari 12.0 也未支持

prefers-color-scheme 在 CSS 变量中的典型用法

最实用的模式是定义两套 CSS 自定义属性，在 :root 下按主题切换，组件直接引用变量，避免重复写选择器。

:root {
  --bg: #fff;
  --text: #333;
}

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

body {
  background-color: var(--bg);
  color: var(--text);
}

• 变量名别用 --dark-bg 这类带主题标识的，统一叫 --bg 更利于维护和后续扩展（比如加高对比度模式）
• 不要在 @media 外直接给 :root 写暗色值，否则亮色用户也会加载暗色变量，造成闪烁或 SSR 不一致
• 若用 CSS-in-JS（如 Emotion、Styled Components），需通过 useEffect + window.matchMedia 手动监听变化，CSS 变量方案在此场景下失效

如何让内联 SVG 或 适配暗色模式

CSS 媒体查询对内联 SVG 的 fill、stroke 无效， 绘图更需 JS 主动判断，不能靠样式自动切换。

• SVG：把颜色写成 fill="var(--icon-color)"，并在 标签上加 style="color: var(--icon-color)"，再通过 currentColor 引用 —— 这样它就能随 :root 变量一起变
• Canvas：用 window.matchMedia('(prefers-color-scheme: dark)').matches 判断，首次绘制和监听 change 事件重绘；注意该 API 同步返回结果，无需 await
• 避免在 Canvas 中硬编码 #000 或 #fff，应提取为配置对象，和 CSS 变量保持语义一致（如 theme.colors.text）

服务端渲染（SSR）时怎么避免闪屏

纯前端判断必然导致首次渲染用亮色、几毫秒后切暗色，出现明显闪烁。解决核心是让服务端知道客户端偏好。

• 无法从 HTTP 请求头直接读取 prefers-color-scheme（它不在标准 header 中），只能靠客户端 JS 上报或 Cookie 记忆
• 常见折中方案：首屏用