必须操作 document.documentElement，不能改 body 或其他容器；需调用 bootstrap.Theme.getOrCreateInstance().update() 刷新变量；自定义颜色须在 :root 和 [data-bs-theme="dark"] 中双重声明；切换时同步 localStorage 以避免闪屏。
必须操作 document.documentElement，不是 body 或其他容器
改 body 或某个 div 的 data-bs-theme 属性，按钮、卡片、表单控件等绝大多数组件都不会响应——因为 Bootstrap 5.3+ 的深色变量作用域基于 :root，而 :root 对应的就是 document.documentElement（即 标签）。常见错误是写成 document.body.setAttribute('data-bs-theme', 'dark')，结果页面毫无变化。
正确写法只有一行：document.documentElement.setAttribute('data-bs-theme', 'dark')
注意值必须是小写字符串 'dark' 或 'light'，不能是 'Dark'、'DARK' 或 true。
切换后必须调用 bootstrap.Theme.getOrCreateInstance().update()
Bootstrap 不会监听 DOM 属性变化自动重算 CSS 变量。只改 data-bs-theme，样式不会实时更新——尤其在 Safari 和部分旧版 Chrome 中，按钮背景、文字颜色可能卡在旧状态。
必须显式触发刷新：
- 确保已加载
bootstrap/js/dist/theme.js（ESM 构建中可用；UMD 版如bootstrap.bundle.min.js默认不导出Theme） - 调用
bootstrap.Theme.getOrCreateInstance(document.documentElement).update() - 若用 CDN，推荐引入完整 ESM 包：
https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.esm.js
漏掉这一步，是“点了没反应”最常被忽略的原因。
立即学习“前端免费学习笔记（深入）”；
自定义颜色必须靠 :root + [data-bs-theme="dark"] 双重声明
Bootstrap 官方 CSS 中的 .btn-primary 等样式依赖 var(--bs-primary)，但这个变量默认只在 [data-bs-theme="dark"] 规则块里被重定义。如果你没自己写这层覆盖，它就永远是浅色值。
必须手动补全两套变量：
:root {
--bs-primary: #0d6efd;
--bs-body-bg: #fff;
--bs-body-color: #212529;
}
[data-bs-theme="dark"] {
--bs-primary: #6ea8ff;
--bs-body-bg: #212529;
--bs-body-color: #f8f9fa;
}
注意顺序：你的自定义 CSS 必须在 Bootstrap 官方 CSS 之后加载，否则变量读不到；且所有自定义组件（如 .card-dashboard）也得统一用 var(--bs-xxx)，不能硬写 #343a40。
持久化要同步 localStorage 并避开闪屏
用户点一次“切暗色”，刷新就回亮色？这不是 Bug，是 Bootstrap 本身不管理状态——data-bs-theme 是瞬时 DOM 属性，不存就丢。
关键三步不能少：
- 点击切换时：同时执行
localStorage.setItem('theme', 'dark')（存字符串，别存布尔值） - 页面加载时：在
DOMContentLoaded后立即读取localStorage.getItem('theme')，设属性并调.update() - 服务端渲染场景（如 Next.js）：初始 HTML 固定为
，JS 加载后再替换，避免白屏/黑屏闪动
最容易被忽略的细节是：localStorage 读取和 .update() 必须在同一个同步流程里完成，否则浏览器可能先按旧主题渲染一帧，再跳变——这就是“闪”。
