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 根本没有定义这些 CSS 变量。
• 尽量避免用 !important 强行覆盖，优先依靠选择器权重（例如 body.bootstrap-dark .btn 的优先级高于 .btn）。
• 建议在浏览器开发者工具中检查“计算样式”，确认最终生效的是深色版本的规则，而不是被前面的浅色样式所截断。

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 被 JavaScript 动态覆盖、自定义组件缺少深色专属规则。这些细节一旦遗漏，整个切换功能就会静默失效——页面看起来“点击没反应”，但实际上问题可能不在 JS 逻辑，而是样式根本没有正确接上。