Bootstrap 4 CSS暗黑主题切换方案

Bootstrap 4 官方未提供 data-bs-theme 属性机制，所有主题切换均需通过 CSS class 驱动。若试图将 Bootstrap 5.3+ 的 document.documentElement.setAttribute('data-bs-theme', 'dark') 直接用于 v4，则无法生效。主流做法是引入第三方暗黑主题包（如 @forevolve/bootstrap-dark），通过覆盖原有类名样式实现切换，核心在于 触发整套深色样式重载，而非依赖 CSS 变量更新。关键点如下：主题 class 必须添加在 上，添加在 或容器 div 中均无效；bootstrap-dark.min.css 需在 bootstrap.min.css 之后加载，避免样式被覆盖；切勿混用多个暗黑主题 CSS 文件（如同时引入 bootstrap-dark 和自定义 dark.css），否则选择器优先级冲突会导致部分组件失效。

切换时必须手动 reload 样式或替换 class，不能只改属性

Bootstrap 4 不具备 bootstrap.Theme.getOrCreateInstance().update() 等 API，也无 CSS 变量重计算机制。所谓“切换”，本质上是 DOM class 变更与浏览器重新匹配样式规则。典型实现通过操作 document.body.className 完成：

const toggleBtn = document.getElementById('theme-toggle');toggleBtn.addEventListener('click', () => {  const body = document.body;  if (body.classList.contains('bootstrap-dark')) {    body.classList.remove('bootstrap-dark');    localStorage.setItem('theme', 'light');  } else {    body.classList.add('bootstrap-dark');    localStorage.setItem('theme', 'dark');  }});

• 避免使用 setAttribute('class', ...) 全量覆盖，否则会丢失其他必要的 class（如 container 所在的 wrapper 类）。
• 初始化时从 localStorage.getItem('theme') 读取，而非仅依赖 prefers-color-scheme，否则用户上次的选择会丢失。
• 若使用 jQuery，应避免 $('body').removeClass().addClass() 这种粗糙写法（会清空所有 class），正确做法为 .toggleClass('bootstrap-dark')。

自定义组件必须显式适配 dark class，否则颜色不变

Bootstrap 4 的按钮、卡片等组件样式通过 CSS 硬编码（如 .btn-primary { background-color: #007bff; }），bootstrap-dark 包仅提供了另一套同名 class 的重写规则。用户自定义的 .card-dashboard 或 .stat-badge 不会自动响应 body.bootstrap-dark，需主动编写对应规则。正确做法是利用父级 class 进行作用域限定：

.card-dashboard {  background-color: #f8f9fa;  color: #212529;}body.bootstrap-dark .card-dashboard {  background-color: #212529;  color: #f8f9fa;}

• 不要在 .card-dashboard 内部使用 var(--bs-bg)，因为 Bootstrap 4 未定义这些变量。
• 避免使用 !important 强行覆盖，应优先依靠选择器权重（如 body.bootstrap-dark .btn 比 .btn 优先级高）。
• 通过浏览器开发者工具的“计算样式”确认最终生效的是 dark 版本规则，而非被浅色规则截断。

prefers-color-scheme 只能做初始值参考，无法自动同步

window.matchMedia('(prefers-color-scheme: dark)') 返回的是当前快照，并非响应式信号。Bootstrap 4 本身不监听该事件，也不会在系统主题切换时自动翻转 body 的 class。如需要自动响应，应自行添加监听逻辑：

const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');function handleThemeChange(e) {  const theme = e.matches  'dark' : 'light';  if (localStorage.getItem('theme') === null) {    document.body.classList.toggle('bootstrap-dark', e.matches);  }}mediaQuery.addEventListener('change', handleThemeChange);handleThemeChange(mediaQuery); // 立即执行一次

• 仅在 localStorage 为空时根据系统偏好设置，否则尊重用户手动选择。
• 绑定监听器应在 DOMContentLoaded 之前，避免错过首次触发。
• Safari 14+ 支持该 API，但 iOS 13.7 及更早版本不支持，需降级 fallback（如默认亮色）。

实际使用中最容易卡住的关键点包括：CSS 加载顺序错误、body class 被 JS 动态覆盖、自定义组件未编写 dark 专属规则。这些环节若出现遗漏，整个切换会静默失败——页面看似“点击无反应”，实际问题并非出在 JS，而是样式未正确接上。