必须调用 bootstrap.theme.getorcreateinstance().update() 才能使 data-bs-theme 属性生效，因 bootstrap 5.3+ 依赖该方法重算 --bs-* css 变量；仅设属性不触发变量更新，样式不会变化。
只改 document.documentElement.setAttribute('data-bs-theme', 'dark') 不会生效，必须同步调用 bootstrap.Theme.getOrCreateInstance().update() 重算 CSS 变量——这是 90% 的人卡住的第一步。
为什么 data-bs-theme 属性设了但样式没变
Bootstrap 5.3+ 的暗黑模式不是纯靠属性选择器驱动的。它依赖两层机制：[data-bs-theme="dark"] 触发作用域，同时 --bs-body-bg 这类变量必须被重新计算。只设属性不刷新变量，所有 var(--bs-*) 值仍维持初始状态。
- 打开开发者工具 → Elements → 选中
:root→ 切换后看--bs-body-bg是否变化；不变 = 没调.update() - UMD 环境下
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()，避免实例绑定错位
自定义组件如何响应主题切换
你写的 .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('ui-theme', next)，别用布尔值，后续加'auto'更平滑 - 刷变量：
bootstrap.Theme.getOrCreateInstance(document.documentElement).update() - 更新 UI：同步切换按钮图标或文字，例如
iconEl.textContent = next === 'dark' ? '?' : '☀️'
容易被忽略的链式变量完整性
只改 --bs-primary 不够。Bootstrap 很多样式依赖 RGB 版本（比如 rgba(var(--bs-primary-rgb), .1)），漏掉 --bs-primary-rgb 就会导致半透明背景、阴影、边框直接 fallback 到默认蓝色。
- 查 Bootstrap 源码里的
_variables.scss，确认哪些变量引用了-rgb后缀值 -
--bs-primary-rgb必须手动设置，且值要精确（如#6f42c1→111, 66, 193，不是四舍五入的111, 66, 192） - Tooltip、modal 等 Portal 渲染组件不会自动重绘，已初始化实例需手动处置再重建
- 真正长期维护多主题，建议把整套变量链打包成对象，用 JS 注入
<style id="theme-styles"></style>，而不是零敲碎打改单个变量
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
