Bootstrap 5.3+ 暗色模式需操作 document.documentElement.setAttribute('data-bs-theme', 'dark')，并配合 localStorage 持久化、使用 CSS 变量、加载完整 CSS 文件及同步图标状态。
点击按钮切换 data-bs-theme 属性必须操作 document.documentElement
Bootstrap 5.3+ 的暗色模式不是靠 class 或 JS 重载 CSS 实现的，核心是 data-bs-theme 这个 HTML 属性。但很多人写成 document.body.setAttribute('data-bs-theme', 'dark')，结果完全没反应——因为 Bootstrap 只监听 document.documentElement（即 <html> 标签）上的该属性变化。
正确做法是：
- 按钮点击时，用
document.documentElement.setAttribute('data-bs-theme', 'dark')或'light' - 同时存入
localStorage.setItem('theme', 'dark')，避免刷新丢失 - 初始化页面时，优先读
localStorage.getItem('theme')，而不是只看prefers-color-scheme，否则用户上次选择会被覆盖 - 别在 CSS 里硬写
background: #fff，所有颜色必须用var(--bs-body-bg)等变量，否则data-bs-theme切换后不生效
为什么切了 data-bs-theme 还是没变黑？检查这三处
常见“不生效”不是代码错，而是环境或配置断链：
-
bootstrap.min.cssCDN 链接是否带深色变量？官方精简版（如某些 CDN 的 -min.css）可能剔除了@media (prefers-color-scheme: dark)和[data-bs-theme="dark"]规则，得换用完整版（如bootstrap.css或明确标注 “with dark mode” 的构建） - 自定义 CSS 是否写在 Bootstrap 之后？如果写了
.card { background: white; }，它会直接覆盖var(--bs-card-bg)，导致主题失效；应改为.card { background: var(--bs-card-bg); } - 浏览器开发者工具里，展开
:root，看--bs-body-bg值是否随data-bs-theme切换而变化。不变，说明 CSS 没加载或规则被覆盖；变了但页面没反应，大概率是上面那条硬编码颜色的问题
自定义主题按钮图标要同步状态，别只改 class
用 Font Awesome 的 fa-sun/fa-moon 图标很常见，但容易只做视觉切换，忽略真实状态同步：
- 图标切换必须和
data-bs-theme值严格一致：当前是dark就显示月亮，light就显示太阳 - 不要只用
icon.classList.toggle('fa-sun', 'fa-moon')，而应先读取当前data-bs-theme值再决定加哪个类，否则用户手动切系统偏好后图标就脱节 - 建议把图标逻辑封装进同一函数：比如
updateThemeToggleIcon()，在初始化、按钮点击、matchMedia回调里都调一次 - 如果项目用了 Vue/React，图标状态应绑定到响应式数据（如
isDark），而非手动 DOM 操作
Bootstrap 原生暗色模式的优缺点很实际
优点很实在：不用自己维护两套变量、组件自动适配（btn、form-control、card 全部开箱即用）、CSS 体积小（复用同一套变量）、与 prefers-color-scheme 天然兼容。
缺点也直击痛点：
- 无法细粒度控制单个组件主题（比如只想让 navbar 暗、其他亮），因为
data-bs-theme是全局开关 - 自定义颜色必须补全整套依赖变量（如改了
--bs-primary，还得配--bs-primary-rgb、--bs-primary-text-emphasis），否则悬停、边框、文字对比度全乱 - 不支持运行时动态生成主题（比如用户调色板选色），因为变量值必须提前写死在 CSS 中或由 JS 注入完整字符串，不能靠计算式生成
- SSR 场景下首次渲染仍可能闪屏，除非服务端能根据请求头或 cookie 提前注入
data-bs-theme属性
真正难的从来不是切换动作本身，而是确保每次切换后，所有组件的颜色语义依然成立——尤其是文字对比度、边框层级、背景透明度这些隐性依赖，最容易在测试遗漏时上线才暴露。
