怎样用Bootstrap 5.3实现CSS深色模式

作者：袖梨 2026-08-17

必须用 document.documentElement 设置 data-bs-theme 且调用 bootstrap.Theme.getOrCreateInstance().update()，否则 CSS 变量不刷新、样式无变化；属性设在 body 或 div 无效，值须为小写 light/dark，update() 必须传 html 元素且 DOM 挂载后执行。

必须用 document.documentElement 设置 data-bs-theme，且每次切换后要调 bootstrap.Theme.getOrCreateInstance().update() —— 漏掉任一环节，样式都不会变。

为什么只改 data-bs-theme 属性没效果

Bootstrap 5.3+ 的深色模式不是靠 CSS 类或 JS 直接改样式，而是靠属性触发 CSS 变量重计算。但变量本身不会自动刷新，必须手动通知 Bootstrap 重新解析。

data-bs-theme 必须设在 document.documentElement（即 <html> 标签），设在 <body> 或任意 div 都无效
属性值只能是 "light" 或 "dark"，大小写敏感，不能写成 "Dark" 或 "dark-mode"
改完属性后，--bs-body-bg、--bs-text-color 等变量仍维持旧值，除非显式调用 bootstrap.Theme.getOrCreateInstance().update()
CDN 引入的 bootstrap.bundle.min.js 默认不暴露 bootstrap.Theme，需额外加载 bootstrap/js/dist/theme.js 或改用 ESM 版本

bootstrap.Theme.getOrCreateInstance().update() 怎么调才对

这个方法不是可选补丁，是主题切换生效的必要步骤。它负责重新读取 data-bs-theme 并更新所有 :root 下的 CSS 变量。

参数必须传 document.documentElement，传 document.body 会静默失败或报错
UMD 环境下（如 CDN），确保 bootstrap/js/dist/theme.js 已加载，否则 bootstrap.Theme 是 undefined
ESM 环境下需先 import { Theme } from 'bootstrap'，再 new Theme(document.documentElement).update()
不要在 DOM 尚未挂载时调用（比如 SSR 场景中，必须等 DOMContentLoaded 或 useEffect）

localStorage 持久化和初始渲染怎么避免闪屏

用户点一次切换，刷新页面就回到浅色——这是没存 localStorage；页面先白再黑/先黑再白——这是初始化时机错了。

服务端或 HTML 模板里，<html> 标签必须硬编码 data-bs-theme="light"（或 "dark"），不能留空或依赖 JS 后置设置
JS 加载后第一件事：读 localStorage.getItem('theme')，fallback 到 window.matchMedia('(prefers-color-scheme: dark)').matches
设完 document.documentElement.dataset.bsTheme 后，**立刻** 调 bootstrap.Theme.getOrCreateInstance().update()，不能延迟
每次点击按钮都要同步写入：localStorage.setItem('theme', next)，存字符串 "light"/"dark"，别存布尔值

CSS 加载顺序和变量覆盖最容易踩坑

即使 JS 全部写对，CSS 层面一个顺序错误或一行硬编码就能让深色模式彻底失效。

@media (prefers-color-scheme: dark) 规则必须放在默认 :root 定义之后，否则旧版 Safari 忽略
自定义 CSS 如果写在 Bootstrap 之后，且用了 background-color: #121212 这类硬编码，会直接覆盖 --bs-body-bg 变量，导致主题切换失效
用 Sass 自定义时，确认启用了 $enable-dark-mode: true，并确保 _variables-dark.scss 被编译进最终 CSS
检查开发者工具的 :root 节点：切换后 --bs-body-bg 值是否真变了？没变就是 update() 没执行，或 CSS 没加载全