要让 Bootstrap 5.3 的深色模式真正生效，下面这几个条件一个都不能缺：data-bs-theme 必须设置在 document.documentElement 上，同时还需要调用 bootstrap.Theme.getOrCreateInstance().update()，否则 CSS 变量根本不会重新刷新，页面样式看起来也不会发生任何变化。尤其要注意，这个属性放在 body 或 div 上都不会生效；取值也必须使用小写的 light/dark；此外，update() 必须传入 html 元素，并且要在 DOM 挂载完成后再执行，这一点才是实现主题切换的关键。
想用 document.documentElement 设置 data-bs-theme 实现 Bootstrap 5.3 深色模式，每次切换后都必须调用 bootstrap.Theme.getOrCreateInstance().update() —— 任何一个步骤遗漏，页面样式都不会切换。
为什么只修改 data-bs-theme 属性没有效果
Bootstrap 5.3+ 的暗黑模式并不是依赖普通 CSS 类名切换，也不是通过 JS 直接改颜色，而是通过属性触发 CSS 变量重新计算。不过这些变量不会自动刷新，所以必须手动通知 Bootstrap 重新解析主题配置。
data-bs-theme必须设置在document.documentElement（也就是标签）上，放在或任何 div 元素上都不会生效- 属性值只能写成
"light"或"dark"，并且大小写敏感，不能写成"Dark"、"DARK"或"dark-mode" - 即使改完属性，像
--bs-body-bg、--bs-text-color这类 CSS 变量也可能依旧保持旧值，除非显式调用bootstrap.Theme.getOrCreateInstance().update() - 如果你是通过 CDN 引入
bootstrap.bundle.min.js，默认情况下并不会暴露bootstrap.Theme，这时还需要额外加载bootstrap/js/dist/theme.js，或者改用 ESM 版本
bootstrap.Theme.getOrCreateInstance().update() 应该怎么调用才正确
这个方法不是可有可无的补丁，而是 Bootstrap 主题切换能否生效的必要步骤。它的作用就是重新读取 data-bs-theme，并同步更新所有挂在 :root 下的 CSS 变量。
- 参数必须传入
document.documentElement，如果传document.body，通常会静默失败，某些场景下也可能直接报错 - 在 UMD 环境中（例如使用 CDN），要先确认
bootstrap/js/dist/theme.js已经成功加载，否则bootstrap.Theme会是undefined - 在 ESM 环境下，需要先
import { Theme } from 'bootstrap'，然后再通过new Theme(document.documentElement).update()完成更新 - 不要在 DOM 还没有挂载完成时调用这个方法，例如 SSR 场景下，必须等到
DOMContentLoaded之后，或者在 React 的useEffect中执行
localStorage 持久化与初始渲染如何避免闪屏
用户点击一次主题切换，刷新页面后又恢复浅色模式——通常是因为没有写入 localStorage；页面先白一下再变黑，或者先黑一下再变白——往往是因为初始化时机不对。
- 在服务端输出或 HTML 模板中，
标签必须直接写好data-bs-theme="light"（或"dark"），不能留空，也不要完全依赖 JS 在后面再设置 - JS 加载完成后的第一件事，就是读取
localStorage.getItem('theme')，如果没有缓存值，再回退到window.matchMedia('(prefers-color-scheme: dark)').matches - 设置完
document.documentElement.dataset.bsTheme后，要立即调用bootstrap.Theme.getOrCreateInstance().update()，不要延迟执行，否则很容易出现页面闪烁 - 每次点击切换按钮时，都要同步写入：
localStorage.setItem('theme', next)，保存的字符串必须是"light"/"dark"，不要存成布尔值
CSS 加载顺序与变量覆盖是最常见的深色模式问题
即使 JavaScript 部分全部写对了，只要 CSS 的加载顺序有问题，或者存在一行颜色硬编码，也足以让 Bootstrap 深色模式彻底失效。
@media (prefers-color-scheme: dark)规则必须写在默认:root定义之后，否则旧版 Safari 可能会直接忽略这部分样式- 如果自定义 CSS 写在 Bootstrap 后面，并且使用了类似
background-color: #121212这样的硬编码颜色，就会直接覆盖--bs-body-bg变量，从而导致主题切换失效 - 如果你使用 Sass 做自定义构建，需要确认已经启用
$enable-dark-mode: true，并确保_variables-dark.scss已经被正确编译进最终输出的 CSS 文件 - 可以打开开发者工具检查
:root节点：切换主题后--bs-body-bg的值有没有真正变化？如果没有变化，通常说明update()没有执行，或者 CSS 资源没有完整加载
真正难处理的往往不是“Bootstrap 5.3 深色模式怎么写”，而是“应该在什么时机写、又该写到什么位置”——document.documentElement、update() 和 localStorage 这三个环节必须严格按顺序配合，少任何一步都不行。只要其中某一步发生异步延迟，或者 DOM 挂载位置稍有偏差，就很容易导致 CSS 变量失效、组件样式不更新，甚至出现页面反复闪屏等常见问题。
