Bootstrap 5.3+ 暗黑模式需手动调用 bootstrap.Theme.getOrCreateInstance().update() 刷新 CSS 变量，且必须加载 theme.js；仅设 data-bs-theme="dark" 无效。
Bootstrap 5.3+ 原生支持暗黑模式，但只设 data-bs-theme="dark" 属性不会自动生效——必须手动触发 CSS 变量重计算，否则页面颜色纹丝不动。
为什么 document.documentElement.setAttribute('data-bs-theme', 'dark') 没反应
根本原因不是 JS 写错了，而是 Bootstrap 的变量系统没刷新。CSS 自定义属性（如 --bs-body-bg）的值不会随 HTML 属性变化自动更新，必须显式调用 bootstrap.Theme.getOrCreateInstance().update()。
- 漏掉这一步，
:root下的变量值在开发者工具里完全不变 -
bootstrap.Theme在 UMD 环境（比如直接 script 引入）下默认不可用，需额外加载bootstrap/js/dist/theme.js - 如果用了打包工具（Webpack/Vite），确保已 import 'bootstrap/js/dist/theme' 或等效逻辑
- 调用时传参要明确：推荐
bootstrap.Theme.getOrCreateInstance(document.documentElement).update()，避免实例作用域错位
切换按钮点击逻辑必须闭环
一个有效切换不只是改属性，还要同步状态、持久化、更新 UI。常见写法只改了 data-bs-theme 却忘了其他环节，导致刷新丢失或图标脱节。
- 必须操作
document.documentElement，不是document.body或某个 div —— Bootstrap 只监听根节点 - 切换后立刻执行
localStorage.setItem('theme', next)，存字符串'light'或'dark'，别存布尔值 - 图标状态（如 Font Awesome 的
fa-sun/fa-moon）应由当前data-bs-theme值决定，而不是靠 toggle 类名来回猜 - 建议封装为统一函数，例如：
function setTheme(theme) { document.documentElement.setAttribute('data-bs-theme', theme); localStorage.setItem('theme', theme); bootstrap.Theme.getOrCreateInstance(document.documentElement).update(); updateToggleIcon(theme); }
初始化时如何避免闪屏和状态覆盖
页面首次渲染前，不能让 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 - 读取
matchMedia必须在DOMContentLoaded之后，否则可能返回undefined - 设置完
dataset.bsTheme后，**立刻** 调用.update()，中间不能有异步延迟 - 自定义 CSS 必须放在 Bootstrap 完整 CSS 之后，且所有颜色都用
var(--bs-body-bg)，禁用硬编码如background: #fff
最易被忽略的是：变量刷新必须手动触发，且 theme.js 不是默认内置的。很多人卡在“明明属性改了却没变色”，其实只是少了一行 .update() 调用，或者 theme.js 根本没加载。
