必须用 document.documentElement 设置 data-bs-theme 且调用 bootstrap.Theme.getOrCreateInstance().update()，否则 CSS 变量不刷新、样式无变化；属性设在 body 或 div 无效，值须为小写 light/dark，update() 必须传 html 元素且 DOM 挂载后执行。
必须用 document.documentElement 设置 data-bs-theme，且每次切换后要调 bootstrap.Theme.getOrCreateInstance().update() —— 漏掉任一环节，样式都不会变。
为什么只改 data-bs-theme 属性没效果
Bootstrap 5.3+ 的深色模式不是靠 CSS 类或 JS 直接改样式，而是靠属性触发 CSS 变量重计算。但变量本身不会自动刷新，必须手动通知 Bootstrap 重新解析。
-
data-bs-theme必须设在document.documentElement（即<html>标签），设在<body>或任意 div 都无效 - 属性值只能是
"light"或"dark"，大小写敏感，不能写成"Dark"或"dark-mode" - 改完属性后，
--bs-body-bg、--bs-text-color等变量仍维持旧值，除非显式调用bootstrap.Theme.getOrCreateInstance().update() - CDN 引入的
bootstrap.bundle.min.js默认不暴露bootstrap.Theme，需额外加载bootstrap/js/dist/theme.js或改用 ESM 版本
bootstrap.Theme.getOrCreateInstance().update() 怎么调才对
这个方法不是可选补丁，是主题切换生效的必要步骤。它负责重新读取 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或useEffect）
localStorage 持久化和初始渲染怎么避免闪屏
用户点一次切换，刷新页面就回到浅色——这是没存 localStorage；页面先白再黑/先黑再白——这是初始化时机错了。
立即学习“前端免费学习笔记（深入）”；
- 服务端或 HTML 模板里，
<html>标签必须硬编码data-bs-theme="light"（或"dark"），不能留空或依赖 JS 后置设置 - JS 加载后第一件事：读
localStorage.getItem('theme')，fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 设完
document.documentElement.dataset.bsTheme后，**立刻** 调bootstrap.Theme.getOrCreateInstance().update()，不能延迟 - 每次点击按钮都要同步写入：
localStorage.setItem('theme', next)，存字符串"light"/"dark"，别存布尔值
CSS 加载顺序和变量覆盖最容易踩坑
即使 JS 全部写对，CSS 层面一个顺序错误或一行硬编码就能让深色模式彻底失效。
-
@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 没加载全
真正麻烦的从来不是“怎么写”，而是“什么时候写”和“写在哪”——document.documentElement、update()、localStorage 三者必须严格按序协同，缺一不可。任何一步异步延迟或 DOM 位置偏差，都会导致变量卡住、组件不响应、页面闪动。
