必须调用 bootstrap.theme.getorcreateinstance(document.documentelement).update() 刷新 css 变量，否则 data-bs-theme="dark" 不生效；umd 需额外引入 theme.js，esm 需 import 'bootstrap/js/dist/theme'；自定义样式须用 css 变量并后于 bootstrap 加载；切换需同步改属性、存 localstorage、刷变量、更新 ui；初始化应优先读 localstorage 再 fallback 系统偏好。
只设 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.getAttribute('data-bs-theme') || 'light' - 计算下一个值：
const next = current === 'light' ? 'dark' : 'light' - 三件事同步做：
document.documentElement.setAttribute('data-bs-theme', next)、localStorage.setItem('theme', next)、bootstrap.Theme.getOrCreateInstance(document.documentElement).update() - 图标状态（如 Font Awesome 的
fa-sun/fa-moon）应由当前data-bs-theme值决定，而不是靠 toggle 类名来回猜
初始化时如何避免闪屏和状态覆盖
服务端或首次加载时，不能让 HTML 默认带 data-bs-theme="dark"；也不能在 JS 执行前就按系统偏好硬设，否则用户上次选择会被清空。
- 服务端/模板中固定输出
，不写auto或猜测值 - JS 加载后立即读取：
const saved = localStorage.getItem('theme')，有值就用它；否则 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 别在
DOMContentLoaded之前读matchMedia，否则可能返回undefined - 设置完
document.documentElement.dataset.bsTheme = 'dark'后，立刻执行bootstrap.Theme.getOrCreateInstance(document.documentElement).update()
最容易被忽略的是变量重计算时机和作用域：update() 必须在属性设置后立刻执行，且必须针对 document.documentElement 实例；任何延迟、错对象、或缺失 theme.js，都会导致切换看起来“点了但没反应”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
