必须调用 bootstrap.Theme.getOrCreateInstance().update() 才能重算CSS变量，否则仅设置 data-bs-theme 属性无效；需确保正确引入 theme.js、检查变量值、避免CSS覆盖、初始化时防止闪屏，并在切换后立即执行 update()。
必须改 document.documentElement 的 data-bs-theme 属性，并手动调用 bootstrap.Theme.getOrCreateInstance().update()，否则样式不会重算——这是最常卡住的地方。
为什么只设 data-bs-theme="dark" 页面没反应
Bootstrap 5.3+ 的深色模式依赖两层机制：CSS 变量（如 --bs-body-bg） + 属性选择器（[data-bs-theme="dark"]）。但变量值不会自动刷新。
- 常见错误是只写
document.documentElement.setAttribute('data-bs-theme', 'dark')，却漏掉后续的.update()调用 - 如果你用的是 UMD 版本（比如
bootstrap.bundle.min.js），bootstrap.Theme可能未定义——需确认是否已单独引入bootstrap/js/dist/theme.js - 检查浏览器开发者工具的
:root节点：切换后--bs-body-bg值没变？那基本就是没调.update() - CSS 加载顺序也很关键：自定义 CSS 若写在 Bootstrap 之后且硬编码了
background: #fff，会直接覆盖变量，导致失效
如何正确初始化主题（避免闪屏）
服务端渲染或首次加载时，不能让 HTML 默认带 data-bs-theme="dark"，否则 JS 还没执行就按深色渲染，用户可能看到短暂白字黑底或布局错乱。
- 服务端/模板中固定输出
- JS 加载后立即读取：
localStorage.getItem('theme')→ 有值则用；否则 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 设置完
document.documentElement.dataset.bsTheme = 'dark'后，**立刻**执行bootstrap.Theme.getOrCreateInstance(document.documentElement).update() - 别在
DOMContentLoaded之前读matchMedia，否则可能返回undefined
切换按钮的最小可行实现
图标按钮本身不复杂，但逻辑链必须完整：点击 → 切属性 → 存 localStorage → 刷新变量 → 更新图标状态。
立即学习“前端免费学习笔记（深入）”；
- 用
<button type="button"></button>，避免表单默认行为干扰 - 存 localStorage 时用字符串
'light'或'dark'，别用布尔值 —— 后续加'auto'模式会更平滑 - 图标建议用 Font Awesome：
fa-sun/fa-moon，通过icon.classList.toggle('fa-sun', next === 'light')控制显隐 - 示例核心逻辑：
document.getElementById('theme-toggle').addEventListener('click', () => {
const html = document.documentElement;
const current = html.getAttribute('data-bs-theme') || 'light';
const next = current === 'light' ? 'dark' : 'light';
html.setAttribute('data-bs-theme', next);
localStorage.setItem('theme', next);
// 关键：必须触发变量重计算
bootstrap.Theme.getOrCreateInstance(html).update();
});
局部深色模式要小心继承泄漏
虽然可以给某个卡片加 <div class="card" data-bs-theme="dark"> 实现局部暗色，但这不是“隔离”的。
<ul>
<li>子组件（如 <code><button class="btn"></button>）会继承该 data-bs-theme，但 Toast、Offcanvas 等浮层类组件仍从 获取主题，容易不一致
data-bs-theme="dark"，又在里面嵌套一个需要亮色背景的表格，就得手动加 data-bs-theme="light" 覆盖，维护成本高bg-light / text-dark）微调，而不是混用属性真正麻烦的从来不是加属性，而是确保每次 DOM 变更后，CSS 变量都同步重算；而最容易被忽略的，是在 SSR 场景下把初始化逻辑塞进 useEffect 或 DOMContentLoaded 之后，却忘了 .update() 必须紧随属性变更之后——差这一行，整个切换就静默失败。
