最轻量可靠的方案是用 prefers-color-scheme 媒体查询配合 CSS 变量:在 :root 定义默认变量,再用 @media (prefers-color-scheme: dark) 覆盖暗色值;手动切换通过 html[data-theme] 属性实现,优先级高于媒体查询,且不破坏系统自动适配逻辑。

直接用 prefers-color-scheme 媒体查询 + CSS 变量控制主题,是最轻量、最可靠、浏览器原生支持的方案。不用 JS 切换 class,不依赖第三方库,也不需要监听系统变化再手动同步状态。
怎么用 prefers-color-scheme 做自动适配
浏览器会根据系统设置(macOS / iOS / Android / Windows)自动匹配 light 或 dark,你只需写两套 CSS 变量定义:
:root {
--bg: #ffffff;
--text: #1f2937;
--card: #f9fafb;
--border: #e5e7eb;
}
<p>@media (prefers-color-scheme: dark) {
:root {
--bg: #111827;
--text: #f9fafb;
--card: #1f2937;
--border: #374151;
}
}所有颜色值都从 --bg、--text 这类变量取,后续改主题只要动变量,不用改每个 background-color。
- 必须把
:root放在@media外面,否则暗色模式下某些浏览器(如旧版 Safari)可能读不到初始值 - 不要用
!important覆盖变量,它会破坏变量链式继承 - 深色背景别用纯黑
#000000,推荐#111827或#1f2937,更护眼也更符合 WCAG 对比度要求
怎么加手动切换按钮(不破坏自动逻辑)
用户想点一下就切,但又不想丢掉“系统默认”这个选项——关键在于用 data-theme 属性覆盖媒体查询,而不是删掉它:
立即学习“前端免费学习笔记(深入)”;
html[data-theme="dark"] {
--bg: #111827;
--text: #f9fafb;
/* 其他变量... */
}
<p>html[data-theme="light"] {
--bg: #ffffff;
--text: #1f2937;
}JS 只负责写属性、存 localStorage,不操作样式:
- 点击按钮时:设置
document.documentElement.setAttribute('data-theme', 'dark') - 页面加载时:先读 localStorage,有值就设属性;没值就什么也不做,让
prefers-color-scheme自动生效 - 不要用
class="dark",因为 class 优先级容易和组件库冲突;data-theme更干净,也方便用 CSS :is() 选择器批量处理
Bootstrap 5 项目里怎么无缝接入
MajesticAdmin 这类基于 Bootstrap 5 的模板本身已用 SCSS 变量组织颜色,直接改 _variables.scss 里的 $body-bg、$text-color 等变量还不够——得让它们响应 prefers-color-scheme:
- 把所有主题色变量改成 CSS 自定义属性,例如
$body-bg: var(--body-bg, #ffffff) - 在
main.scss顶层用@media (prefers-color-scheme: dark)重定义--body-bg等变量 - 禁用 Bootstrap 默认的深色工具类(如
.bg-dark),它们是静态的,和响应式主题冲突 - 如果用了
bootstrap-icons,图标颜色也要通过color: var(--text)控制,不能写死fill="#6b7280"
移动端 Safari 和老安卓 WebView 容易踩的坑
iOS 13+、Android 10+ 原生支持 prefers-color-scheme,但低版本或 WebView(比如某些车机系统)不认:
- CarMore 那类应用在安卓 4.4 车机上跑,得 fallback 到 localStorage + 手动 class 切换,
prefers-color-scheme直接忽略 - Safari 在「浅色模式下打开网页,再切系统为深色」时,不会触发重绘,得监听
storage事件并强制location.reload()(仅限必须强同步的场景) -
<meta name="color-scheme" content="light dark">必须加在里,否则 iOS Safari 不会启用深色表单控件(如<input type="range">滑块)
真正麻烦的不是切换逻辑,而是确保所有颜色路径都经过同一组变量——漏掉一个 svg fill、一个 box-shadow、或者第三方图表库的 theme 配置项,整个仪表盘就会在深色模式下突然“破相”。



















