Bootstrap 5.3+ 深色模式必须设 data-bs-theme 于 document.documentElement 并调用 bootstrap.Theme.getOrCreateInstance().update() 刷新 CSS 变量，否则 --bs-body-bg 等值不更新；自定义组件需用 var(--bs-*) 变量且 CSS 必须在 Bootstrap 后加载。
data-bs-theme 属性没设在 document.documentElement 上
Bootstrap 5.3+ 的深色模式只响应 html 根节点的 data-bs-theme="dark"，设在 <body> 或某个 <div> 上，--bs-body-bg 这类 CSS 变量根本不会重算。很多升级后失效的情况，就是 JS 里写了 document.body.setAttribute('data-bs-theme', 'dark') —— 这完全无效。
漏掉 bootstrap.Theme.getOrCreateInstance().update() 调用
仅设置属性，CSS 变量不会自动刷新。浏览器不会监听 DOM 属性变化，必须手动触发重计算：
- ESM 环境：确保已
import 'bootstrap/js/dist/theme'，再调用new bootstrap.Theme(document.documentElement).update() - UMD 环境（如直接引入
bootstrap.bundle.min.js）：bootstrap.Theme默认未定义，需额外加载bootstrap/js/dist/theme.js，再执行bootstrap.Theme.getOrCreateInstance(document.documentElement).update() - 检查开发者工具 Elements 面板中
:root下的--bs-body-bg值：切换前后不变？基本就是没调.update()
CSS 加载顺序或硬编码颜色覆盖了变量
即使属性和 JS 都对了，样式仍不生效，大概率是 CSS 层面被覆盖：
- 自定义 CSS 写在 Bootstrap 之后，但用了
background: #fff这类硬编码值，直接绕过var(--bs-body-bg) - 确认你用的是完整版 CSS（如
bootstrap.min.css），不是精简构建版 —— 后者可能缺失@media (prefers-color-scheme: dark)和[data-bs-theme="dark"]规则 - 检查是否启用了
$enable-dark-mode: true（Sass 用户）；若自己编译但没引入_variables-dark.scss，深色变量为空，设了data-bs-theme也白搭
组件没读 CSS 变量，只靠 class 不够
Bootstrap 自身组件（如 .btn、.card）会响应主题，但你写的自定义类（比如 .dashboard-header）不会自动变色：
立即学习“前端免费学习笔记（深入）”；
- 所有颜色、背景、边框必须显式使用
var(--bs-body-bg)、var(--bs-primary)等，不能写死#343a40 - 局部启用时（如给某个
<div class="card" data-bs-theme="dark">），注意 Modal、Toast 这类挂载到document.body的组件仍按根主题渲染，会出现样式断裂 - 导航栏例外：它不走
data-bs-theme，得用navbar-dark bg-dark类组合，否则文字/图标对比度不对
