Bootstrap 5.3+ 通过 data-bs-theme 属性支持深色/浅色模式切换，需手动实现按钮与 localStorage 持久化，并调用 bootstrap.Theme.getOrCreateInstance().update() 刷新 CSS 变量。
如何用 Bootstrap 5.3+ 原生支持切换深色/浅色模式
bootstrap 5.3 起内置了 data-bs-theme 属性和 prefers-color-scheme 自动适配，但**不自动提供切换按钮或状态持久化**——你得自己补上这两块。
核心逻辑是：改 <html> 或 <body> 的 data-bs-theme 值为 "light" 或 "dark"，再触发一次 Bootstrap 的内部主题刷新（靠 bootstrap.Theme 实例）。
- 必须用 Bootstrap 5.3.0+，旧版本无
data-bs-theme支持 -
<html data-bs-theme="light">是起点，不能只写在<body> - 切换后需手动调用
bootstrap.Theme.getOrCreateInstance(document.documentElement).update()，否则 CSS 变量不会重算
切换按钮怎么写才不破坏 SSR 和初始渲染
服务端渲染（如 Next.js、SSR 模板）下，如果 JS 还没执行就按 data-bs-theme="dark" 渲染，用户会先看到闪屏（尤其深色背景+浅色文字）。解决方案是：初始 HTML 固定为 data-bs-theme="light"，JS 加载后再根据用户偏好或 localStorage 补上真实值并更新。
- 服务端永远输出
<html data-bs-theme="light">，不猜偏好 - JS 加载后立即读
localStorage.getItem('theme')或window.matchMedia('(prefers-color-scheme: dark)').matches - 设置完
document.documentElement.dataset.bsTheme后，立刻调用new bootstrap.Theme(document.documentElement).update() - 按钮本身建议用
<button type="button">，避免表单提交干扰
localStorage 存什么、什么时候存、为什么不能只存布尔值
存字符串 "light" 或 "dark"，而不是 true/false。因为 Bootstrap 的 data-bs-theme 值是字符串，且后续扩展（比如加 "auto"）需要明确语义。
- 每次点击切换按钮时，必须同步写入
localStorage.setItem('theme', 'dark')（或'light'） - 不要在
DOMContentLoaded里读取后直接设dataset.bsTheme就结束——忘了调用.update()，样式不会变 - 若用户关闭浏览器又打开，仅靠
localStorage恢复主题，prefers-color-scheme不会自动触发，所以别依赖它做初始化
遇到 Uncaught TypeError: bootstrap.Theme is not a constructor 怎么办
这是最常卡住的地方：你用了 Bootstrap 的 ES 模块构建（bootstrap/dist/js/bootstrap.esm.js），但没正确导入 Theme 类，或者用了 CDN 的 UMD 版本（bootstrap.bundle.min.js）却试图直接访问 bootstrap.Theme。
- CDN 用户：必须用
https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js（带 bundle），UMD 全局对象才有bootstrap.Theme - ESM 用户：要显式导入
import { Theme } from 'bootstrap'，不能从bootstrap/dist/js/bootstrap.esm.js直接解构 - 检查控制台是否报
Failed to resolve module specifier "bootstrap"——路径错了，ESM 下必须用完整包名或相对路径
真正麻烦的不是切颜色，而是让切换在 SSR、缓存、多标签页之间保持一致；localStorage 写了但没调 .update()，或者用了 bundle 却当 ESM 用，这两个点几乎占了 80% 的失败案例。
