Bootstrap深色模式必须配合[data-bs-theme="dark"]属性与CSS变量定义，仅用@media (prefers-color-scheme: dark)无法生效，因其不触发Bootstrap主题上下文切换；正确做法是JS监听系统偏好并设置data-bs-theme，再通过[data-bs-theme="dark"]块覆盖--bs-primary等关键变量，且顺序须为:root明色→[data-bs-theme="dark"]暗色→Bootstrap CSS后加载。
直接用 @media (prefers-color-scheme: dark) 覆盖 CSS 变量即可，但必须配合 data-bs-theme 属性和正确的变量定义顺序，否则按钮、卡片等组件不会响应系统切换。
为什么只写 @media (prefers-color-scheme: dark) 不生效
常见错误是把媒体查询写成这样：
:root {
--bs-primary: #0d6efd;
}
@media (prefers-color-scheme: dark) {
:root {
--bs-primary: #6ea8ff;
}
}
这看起来合理，但 Bootstrap 5.3+ 的组件样式（比如 .btn-primary）默认不读取 :root 下的变量——它只在 [data-bs-theme="dark"] 选择器下才重定义变量。单纯靠系统偏好触发 :root 变更，Bootstrap 内部的样式规则没匹配上，所以颜色不变。
- Bootstrap 的深色模式逻辑依赖
[data-bs-theme="dark"]这个属性选择器来激活变量重写，不是靠:root自动更新 -
@media (prefers-color-scheme: dark)在 CSS 里只能影响你写的规则，不能“通知” Bootstrap 切换主题上下文 - 浏览器支持该媒体查询，但 Bootstrap 不监听它；它只响应 HTML 元素上的
data-bs-theme值
正确做法：CSS + data-bs-theme 协同
真正能响应系统主题的方案，是让 CSS 媒体查询自动设置 data-bs-theme 属性值，再由 Bootstrap 的变量机制接管渲染。但注意：HTML 元素不支持在 CSS 里设置属性，所以得靠 JS 初始化，CSS 只负责兜底和覆盖。
立即学习“前端免费学习笔记（深入）”；
- 初始 HTML 必须带
<html data-bs-theme="light">或留空（不推荐），避免闪屏 - JS 加载后立即执行：
document.documentElement.setAttribute('data-bs-theme', window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') - 然后在 CSS 中，用
[data-bs-theme="dark"]块覆盖所有关键变量，例如：
:root {
--bs-primary: #0d6efd;
--bs-body-bg: #fff;
--bs-body-color: #212529;
}
[data-bs-theme="dark"] {
--bs-primary: #6ea8ff;
--bs-body-bg: #212529;
--bs-body-color: #f8f9fa;
}
这个顺序不能颠倒：:root 定义明色系 → [data-bs-theme="dark"] 覆盖暗色系 → Bootstrap CSS 在其后加载（确保它读到的是最终变量值）。
哪些变量必须同步改，否则组件失色
只改 --bs-primary 是不够的。Bootstrap 多数组件依赖衍生变量，漏掉会导致悬停、边框、文字对比度异常。以下是最常出问题的几个：
-
--bs-primary-rgb：用于rgba(var(--bs-primary-rgb), .1)类背景，必须按格式提供 RGB 字符串，如"110, 168, 255" -
--bs-primary-text-emphasis：控制.text-primary在深色背景下的可读性，默认不随主题变，需手动设为浅色（如#6ea8ff） -
--bs-primary-border-subtle：卡片、输入框边框常用，建议设为比主色略浅（如#4a7bff） -
--bs-body-bg和--bs-body-color：直接影响.bg-body、.text-body等基础类，必须配对调整
检查方式：打开 DevTools，选中一个 .btn-primary，看 background-color 计算值是否是你设的暗色值；如果不是，说明对应变量没被 [data-bs-theme="dark"] 覆盖，或选择器优先级不够。
localStorage 持久化时容易忽略的点
用户手动点按钮切换主题后存到 localStorage，下次打开页面要还原。但很多人忘了这三件事：
- 存的值必须是字符串
"light"或"dark"，不能存布尔值true/false，因为data-bs-theme只认这两个字符串 - 恢复时不能只设属性：
document.documentElement.dataset.bsTheme = savedTheme，还必须立刻调用bootstrap.Theme.getOrCreateInstance(document.documentElement).update()，否则 CSS 变量不重算 - 服务端渲染（SSR）场景下，初始 HTML 一律输出
<html data-bs-theme="light">，JS 加载后再覆盖——否则首屏可能白底黑字闪一下再变暗，尤其在深色模式下极易刺眼
最易被忽略的是：系统偏好变化（比如 macOS 设置里切夜间模式）不会自动触发页面更新，window.matchMedia 需手动监听并重新设 data-bs-theme，否则用户改了系统设置，网页还是旧主题。
