必须同步调用 bootstrap.Theme.getOrCreateInstance().update() 才能使 data-bs-theme="dark" 生效，否则 CSS 变量如 --bs-body-bg 不会重算；UMD 需额外引入 theme.js，ESM 需 import 'bootstrap/js/dist/theme'；自定义组件须用 CSS 变量并确保样式表加载顺序正确；切换主题需四步闭环：改属性、存 localStorage、刷变量、更新 UI；初始化应 JS 加载后立即读取 localStorage 或系统偏好并 update()。
只改 data-bs-theme="dark" 属性不会生效，必须同步调用 bootstrap.Theme.getOrCreateInstance().update() 刷新 CSS 变量——这是 90% 的人卡住的第一步。
为什么 document.documentElement.setAttribute('data-bs-theme', 'dark') 没反应
根本不是 JS 写错了，而是 --bs-body-bg 这类变量压根没重算。Bootstrap 5.3+ 的暗黑模式依赖属性触发 + 变量重计算双机制，漏掉后者，样式就冻结在初始状态。
检查方法：打开浏览器开发者工具 → 查看 :root 节点 → 切换后 --bs-body-bg 值不变？说明 bootstrap.Theme.getOrCreateInstance().update() 没执行。
- 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()，避免实例作用域错位
自定义组件如何响应 data-bs-theme 切换
你写的 .card-dashboard、.badge-status 不会自动变色，因为它们没读 CSS 变量——Bootstrap 只管自己的 btn、card，不接管你的代码。
立即学习“前端免费学习笔记（深入）”；
- 所有自定义颜色必须用
var(--bs-body-bg)、var(--bs-primary)，不能硬写#fff或rgb(33, 37, 41) - 自定义 CSS 必须在 Bootstrap 官方 CSS 之后加载，并显式声明两套变量：
:root定义浅色值，[data-bs-theme="dark"]覆盖深色值 - 顺序不能错：先
:root { --bs-primary: #0d6efd; }，再[data-bs-theme="dark"] { --bs-primary: #6ea8ff; } - 检查“计算样式”里背景色是否解析为深色值——如果不是，要么变量没覆盖，要么选择器优先级不够（可加
!important临时验证）
切换按钮的最小可行闭环逻辑
点击一次只改属性，下次刷新就回退；图标和实际主题脱节，用户会困惑。完整链路必须包含四件事：改属性、存本地、刷变量、更新 UI。
- 按钮点击时，读当前
data-bs-theme值：const current = document.documentElement.dataset.bsTheme - 设新值：
document.documentElement.dataset.bsTheme = next - 存入
localStorage：localStorage.setItem('theme', next)（用字符串，别用布尔） - 立刻执行
bootstrap.Theme.getOrCreateInstance(document.documentElement).update() - 同步更新按钮图标状态（例如用 Font Awesome 的
fa-sun/fa-moon类切换）
最易被忽略的是初始化阶段：页面首次加载时，不能等 DOMContentLoaded 再读 localStorage 或 matchMedia，否则会闪白；也不能把 data-bs-theme="dark" 写死在 HTML 里，否则 SSR 场景下可能渲染错乱。正确做法是服务端输出 data-bs-theme="light"，JS 加载后立即读 localStorage → fallback 到系统偏好 → 设置属性 → 立即 update()。
