必须调用bootstrap.Theme.getOrCreateInstance(document.documentElement).update()刷新CSS变量，否则仅设置data-bs-theme="dark"无效；需额外引入theme.js（UMD）或import（ESM），自定义样式须用CSS变量并后于Bootstrap加载，切换时须同步改属性、存localStorage、刷变量、更新UI。
只设 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。
立即学习“前端免费学习笔记（深入）”；
- 改属性：
document.documentElement.setAttribute('data-bs-theme', next)，值只能是小写'light'或'dark' - 存 localStorage：
localStorage.setItem('theme', next)，别存布尔值，为后续'auto'预留扩展空间 - 刷变量：
bootstrap.Theme.getOrCreateInstance(document.documentElement).update()，必须紧接在 setAttribute 之后 - 更新 UI：比如用 Font Awesome 图标，通过
icon.classList.toggle('fa-sun', next === 'light')控制显隐
最易被忽略的是初始化时机：不要等 DOMContentLoaded 再读 localStorage，更不要直接 fallback 到 prefers-color-scheme——页面可能已按系统偏好渲染一帧，再 JS 覆盖就会闪屏。应该在 HTML 根标签上预设 data-bs-theme="light"，JS 加载后立即读取并刷新。
