必须通过注入完整 :root 变量覆盖 Bootstrap 5 主题，而非操作 class 或 document.documentElement.style；需预置全部关联变量（如 --bs-primary、--bs-primary-rgb 等），并在 HTML 解析前注入 。
直接操作 :root 变量是唯一可靠路径
Bootstrap 5 不再提供主题 JS 控制逻辑，所有颜色、间距、阴影都由 CSS 自定义属性驱动。硬写 .dark .btn 类或靠 class="theme-dark" 切换整套 class 是错的——它和 Bootstrap 内置的 .btn-dark、.bg-light 冲突，且无法覆盖组件内部计算色（如 rgba(var(--bs-primary-rgb), .1)）。必须用 :root 级变量统一接管。
关键不是“加新样式”，而是“替换源头”。每个主题必须导出完整变量对象，包含所有 Bootstrap 依赖链变量：
-
--bs-primary和配套的--bs-primary-rgb、--bs-primary-text-emphasis、--bs-primary-bg-subtle、--bs-primary-border-subtle -
--bs-body-bg必须同步--bs-body-color，否则文字在浅背景上不可读 - 不要漏掉
--bs-emphasis-color和--bs-secondary-color，它们被卡片、徽章、进度条等大量引用
注入 <style id="theme-styles"></style> 而非修改 document.documentElement.style
直接写 document.documentElement.style.setProperty('--bs-primary', '#20c997') 看似简单，但无法批量更新、不支持嵌套计算、不能复用主题配置、且每次都要手动补全所有依赖变量。更糟的是：它绕过了 CSS 层叠机制，某些通过 var(--bs-primary-rgb) 引用的地方会 fallback 到浏览器默认值。
正确做法是生成完整 CSS 字符串并注入固定 <style></style> 标签：
立即学习“前端免费学习笔记（深入）”；
const themes = {
light: {
'--bs-primary': '#0d6efd',
'--bs-primary-rgb': '13, 110, 237',
'--bs-primary-text-emphasis': '#084298',
'--bs-primary-bg-subtle': '#cfe2ff',
'--bs-primary-border-subtle': '#a6b7e9',
'--bs-body-bg': '#fff',
'--bs-body-color': '#212529'
},
ocean: {
'--bs-primary': '#20c997',
'--bs-primary-rgb': '32, 201, 151',
'--bs-primary-text-emphasis': '#0a5c4a',
'--bs-primary-bg-subtle': '#d5f9f1',
'--bs-primary-border-subtle': '#aaf2e2',
'--bs-body-bg': '#f8fbff',
'--bs-body-color': '#334155'
}
};
function applyTheme(name) {
const styleEl = document.getElementById('theme-styles');
const vars = Object.entries(themes[name])
.map(([k, v]) => `${k}: ${v}`)
.join('; ');
styleEl.textContent = `:root { ${vars} }`;
}
这个 <style id="theme-styles"></style> 必须放在 中，并确保在 Bootstrap 的 CSS 之后、任何自定义组件样式之前加载。
切换前必须从 localStorage 同步读取，且置于
页面首次渲染时若未提前设置主题，会出现“闪白”或“闪黑”——因为浏览器先按默认 :root 渲染一次，JS 再改，用户肉眼可见颜色跳变。解决方案只有一个：把初始化脚本塞进 第一行，在任何 CSS 解析前就执行。
错误写法：DOMContentLoaded 里读 localStorage 并设 theme → 已晚；正确写法：
<head>
<script>
const savedTheme = localStorage.getItem('theme') || 'light';
document.documentElement.dataset.theme = savedTheme;
// 注意：这里不调用 applyTheme()，只设 data-theme，避免重复写入 style
</script>
<link rel="stylesheet" href="bootstrap.min.css">
<style id="theme-styles"></style>
</head>
后续 JS 只负责更新 #theme-styles 内容，不再动 dataset ——dataset 仅用于初始状态锁定和媒体查询 fallback 判断。
第三方组件主题不一致？别碰它的 class，只管喂它变量
像 Bootstrap Table、Flatpickr、Chart.js 这类组件，只要它们内部用了 var(--bs-primary)，你就不需要额外适配。但如果它写死 #007bff 或用 JS 直接设 style.color，那它就是主题不友好组件。
应对策略只有两个：
- 优先选已声明支持 CSS 变量的主题插件（例如 Bootstrap Table 的
data-theme="bootstrap5"模式） - 对不兼容组件，用
[data-theme="dark"] .flatpickr-calendar这类选择器做最小化覆盖，只修正背景、文字、边框三处，不重写整个结构 - 绝对不要给第三方组件加
class="btn-primary"之类 Bootstrap 类名来“借色”——它会和你的主题变量脱节
真正难的从来不是写切换按钮，而是确认每个主题对象是否补全了全部 12+ 个关联变量，以及是否在首屏 HTML 构建完成前就完成了 :root 注入。漏一个 --bs-primary-rgb，悬停态按钮就会变成半透明黑块。
