必须调用bootstrap.Theme.getOrCreateInstance().update()刷新CSS变量，仅设置data-bs-theme属性无效；需加载theme.js、使用var(--bs-xxx)声明颜色、初始化时读localStorage并避免闪屏。
只改 data-bs-theme 属性不会让页面变暗——CSS 变量必须手动重算，否则 --bs-body-bg、--bs-primary 这些值根本不变。
为什么 document.documentElement.setAttribute('data-bs-theme', 'dark') 没反应
根本不是 JS 写错了，而是 Bootstrap 的变量系统没刷新。CSS 自定义属性（比如 --bs-body-bg）的值不会随 HTML 属性变化自动更新，必须显式调用 bootstrap.Theme.getOrCreateInstance().update()。
- 检查开发者工具的
:root节点：切换后--bs-body-bg值没变 → 没调.update()或theme.js没加载 -
bootstrap.Theme在 UMD 环境（如直接<script>引入）下默认不可用，需额外引入bootstrap/js/dist/theme.js - 打包工具（Vite/Webpack）中需
import 'bootstrap/js/dist/theme'，否则bootstrap.Theme是undefined - 调用时必须传
document.documentElement，传document.body会静默失败或报错
如何让自定义组件也响应 data-bs-theme 切换
你写的 .card-dashboard、.badge-status 不会自动变色，因为它们没读 CSS 变量——硬编码颜色会直接覆盖变量。
- 所有自定义样式必须用
var(--bs-xxx)，不能写死background: #fff或color: #333 - 必须在
:root和[data-bs-theme="dark"]中双重声明变量，例如：:root { --bs-primary: #0d6efd; --bs-body-bg: #fff; } [data-bs-theme="dark"] { --bs-primary: #6ea8ff; --bs-body-bg: #212529; } - 你的自定义 CSS 必须在 Bootstrap 官方 CSS 之后加载，否则变量读不到
- 检查“计算样式”里
background-color最终值：如果是硬编码色值，说明变量被覆盖或选择器优先级不够
初始化时如何避免闪屏和状态丢失
服务端或首次渲染前，不能让 HTML 默认带 data-bs-theme="dark"，否则 JS 还没执行就按深色渲染，用户可能看到白字黑底或布局错位。
立即学习“前端免费学习笔记（深入）”；
- 服务端/模板中固定输出
<html data-bs-theme="light">，不写auto或猜测值 - JS 加载后立即读取：
const saved = localStorage.getItem('theme')；有值就用它，否则 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 设置完
document.documentElement.setAttribute('data-bs-theme', theme)后，**立刻**执行bootstrap.Theme.getOrCreateInstance(document.documentElement).update() - 切换按钮点击逻辑要闭环：改属性 → 存
localStorage.setItem('theme', 'dark')→ 刷新变量 → 更新图标（如fa-sun/fa-moon），缺一不可
最常被忽略的是 .update() 调用时机和自定义 CSS 的变量写法——变量没重算，或者写了 background: white 却指望它跟着主题变，这两处卡住 90% 的实际项目。
