必须调用bootstrap.theme.getorcreateinstance().update()刷新css变量，否则仅设置data-bs-theme="dark"无效；变量未重算导致按钮、卡片等组件颜色不变。
只改 data-bs-theme 属性页面不会变暗，CSS 变量不重算就等于没切换——这是最常卡住的地方。
为什么设置了 data-bs-theme="dark" 但按钮/卡片颜色不变
Bootstrap 5.3+ 的暗黑模式靠两层联动：HTML 属性触发 + CSS 变量重计算。漏掉任意一层都会失效。
- 检查浏览器开发者工具的
:root节点：切换后--bs-body-bg值没变？说明bootstrap.Theme.getOrCreateInstance().update()没执行 - 确认引入的是完整版 CSS（如
bootstrap.css），CDN 上的bootstrap.min.css常精简掉深色变量规则 -
data-bs-theme必须设在document.documentElement（即标签），设在或某个<div> 上完全无效 <li>值必须是小写字符串 <code>"dark"或"light"，不能是"Dark"、true、1 - 所有自定义颜色必须用
var(--bs-body-bg)、var(--bs-primary)，不能写死#fff或rgb(33, 37, 41) - 自定义 CSS 文件必须在 Bootstrap 官方 CSS 之后加载，否则变量读不到
- 必须显式声明两套变量：
:root定义浅色值，[data-bs-theme="dark"]覆盖深色值，顺序不能反 - 如果“计算样式”里背景色还是浅色值，要么变量没覆盖，要么选择器优先级不够（可临时加
!important验证） - UMD 环境（比如直接
<script src="bootstrap.bundle.min.js"></script>）下，bootstrap.Theme默认不可用，必须额外引入bootstrap/js/dist/theme.js - ESM 环境需确保已
import 'bootstrap/js/dist/theme'，否则调用会报Cannot read properties of undefined - 推荐传参
document.documentElement：bootstrap.Theme.getOrCreateInstance(document.documentElement).update()，避免实例作用域错位 - 切完属性后立刻执行
.update()，别等DOMContentLoaded或其他事件——延迟会导致短暂样式错乱 - 服务端/模板中固定输出
- JS 加载后立即读取
localStorage.getItem('theme')→ 有值则用；否则 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 设置完
document.documentElement.dataset.bsTheme = 'dark'后，**立刻**执行bootstrap.Theme.getOrCreateInstance(document.documentElement).update() -
localStorage存字符串"light"或"dark"，别存布尔值——后续加"auto"模式会更平滑
自定义 CSS 必须用 var(--bs-xxx)，不能硬写颜色值
你写的 .card-dashboard、.badge-status 不会自动变色，因为 Bootstrap 只管自己的组件，不接管你的代码。
切换后必须手动调用 bootstrap.Theme.getOrCreateInstance().update()
Bootstrap 不监听 DOM 属性变化，只改 data-bs-theme 属性，CSS 变量不会自动刷新。
初始化时如何避免闪屏
服务端或首次加载时，不能让 HTML 默认带 data-bs-theme="dark"，否则 JS 还没执行就按深色渲染，用户会看到白字黑底或布局错乱。
真正容易被忽略的不是怎么写切换按钮，而是变量重计算和 CSS 加载顺序这两环——它们不出错，切换才真正“可见”。
