Bootstrap 5.3+ 通过替换 标签的 href 动态切换主题，需预编译符合官方变量规范的深/浅色 CSS 文件，配合 localStorage 持久化与 load 事件确保样式生效后保存，避免闪屏、竞态和样式断裂。
如何用 Bootstrap 5 的 CSS 变量 + link 标签动态切换主题
Bootstrap 5.3+ 原生支持主题换肤，靠的是 :root 中定义的 CSS 自定义属性（如 --bs-primary）和外部主题 CSS 文件的按需加载。不是靠 JS 改 class 或重写样式表，而是替换整个 —— 这是最轻量、最可靠的方式。
关键点：所有主题 CSS 必须基于 Bootstrap 的 SCSS 源码编译，且只覆盖变量，不重写组件规则；否则切换后布局/间距会错乱。
- 准备两套主题 CSS：
bootstrap-dark.css（深色变量）、bootstrap-light.css（默认浅色），都从官方scss/_variables.scss衍生编译 - HTML 中只保留一个
，不要多加其他bootstrap.css - 切换时用 JS 替换
href，并触发一次prefers-color-scheme同步逻辑（避免系统主题变化后页面不同步）
为什么不能直接用 document.body.classList.toggle() 加 dark-mode 类
Bootstrap 官方不提供 dark-mode 类切换机制。强行加 class="dark-mode" 并写一堆 .dark-mode .btn { ... } 规则，会导致：
- 所有组件颜色、阴影、边框、文字对比度都要手动重写，维护成本爆炸
- 第三方 Bootstrap 组件（如 Datepicker、Toast）完全不受控，样式断裂
- 响应式断点、栅格行为、辅助类（
text-white、bg-dark）不会自动适配，必须额外写媒体查询 - 无法利用
prefers-color-scheme: dark原生能力，用户系统设为深色时页面仍亮着
localStorage 保存主题选择 + 页面加载时自动应用
用户选了深色，刷新后得记住。但不能在 里就执行 JS（可能阻塞渲染），也不能等 DOMContentLoaded 再换——会闪屏（先亮后暗）。
正确做法：在 底部插入内联脚本，同步读取 localStorage 并设置 的 href：
<script>
const savedTheme = localStorage.getItem('theme') || 'light';
const themeLink = document.getElementById('theme-link');
themeLink.href = savedTheme === 'dark'
? 'bootstrap-dark.css'
: 'bootstrap-light.css';
</script>
- 必须放在
标签之后，否则getElementById找不到 - 不要用
fetch()或异步加载 CSS，会延迟渲染，造成白屏或样式跳变 - 如果服务端能判断首次访问（如无 Cookie），可 fallback 到
window.matchMedia('(prefers-color-scheme: dark)').matches
按钮点击切换时，如何避免重复加载和竞态问题
用户快速连点两次「切换主题」，可能触发两次 href 设置，导致第二次加载被浏览器缓存跳过，或 CSS 解析顺序错乱。
- 加节流：用
disabled状态锁住按钮，CSS 加pointer-events: none防止多次触发 - 监听
load事件而非直接设完就存localStorage，确保新 CSS 已生效再保存 - 示例逻辑：
button.disabled = true; themeLink.addEventListener('load', () => { localStorage.setItem(...); button.disabled = false; }) - 别用
import或dynamic import()加载 CSS —— 它们不触发load事件，也无法控制的 DOM 属性
主题切换真正的复杂点不在 JS，而在主题 CSS 的构建一致性：变量名必须与 Bootstrap 5.3+ 的 scss/_variables.scss 完全对齐，连注释位置都不能错，否则编译后缺失变量，按钮、表单、卡片会集体失色。这个细节，90% 的教程都漏掉了。
