必须用css自定义属性（如--bs-primary）替代sass硬编码值，配合prefers-color-scheme媒体查询与localstorage手动切换，才能实现可靠暗黑模式；仅重编译$theme-colors仅生成静态配色，无法运行时响应。
为什么直接改 $theme-colors 不足以实现可靠的暗黑模式
Bootstrap 5 默认通过 Sass 变量（如 $primary、$body-bg）控制主题，但这些变量在编译时固化为 CSS 常量，无法运行时切换。硬改 $theme-colors 并重新编译只生成一套配色，不支持用户手动开关或系统偏好同步。
真正可维护的暗黑模式需要：运行时响应 prefers-color-scheme、支持用户覆盖、保留 Bootstrap 组件语义类（如 btn-primary）的行为一致性。
- 必须用 CSS 自定义属性（
--bs-primary等）替代硬编码颜色值 - 所有 Bootstrap 颜色类需从自定义变量计算，而非直接写死
#0d6efd - 暗黑模式不能仅靠
html.dark类暴力覆盖，否则会破坏btn-outline-secondary这类依赖对比度的组件逻辑
如何把 Bootstrap 5 的 Sass 颜色体系映射到 CSS 变量
Bootstrap 5.3+ 已内置部分 CSS 变量（如 --bs-primary），但默认未启用完整变量链。你需要在引入 Bootstrap CSS 前，注入一组「可被重写的根级变量」，再让 Bootstrap 的 CSS 规则引用它们。
关键操作是覆盖其 :root 中的变量，并确保后续所有组件样式都基于这些变量计算：
:root {
--bs-primary: #0d6efd;
--bs-primary-rgb: 13, 110, 253;
--bs-primary-text: #fff;
--bs-body-bg: #fff;
--bs-body-color: #212529;
}
<p>@media (prefers-color-scheme: dark) {
:root {
--bs-primary: #6ea8fe;
--bs-primary-rgb: 110, 168, 254;
--bs-primary-text: #000;
--bs-body-bg: #212529;
--bs-body-color: #f8f9fa;
}
}</p><p>/<em> 必须显式声明 dark 主题类，用于用户手动切换 </em>/
html.dark {
--bs-primary: #6ea8fe;
--bs-body-bg: #212529;
--bs-body-color: #f8f9fa;
}
</p>
注意：--bs-primary-rgb 必须同步更新，因为 Bootstrap 内部很多透明度效果（如 btn-hover）依赖 rgba(var(--bs-primary-rgb), .1)。
怎样让 btn、form-control 等组件自动响应变量变更
Bootstrap 5.3 的 CSS 已大量使用 var(--bs-*)，但仍有部分地方回退到 Sass 编译值（比如某些阴影、边框色）。最稳妥的方式是：在 Bootstrap CSS 后加载一层「变量补丁」，强制重写关键选择器。
- 按钮悬停背景：重写
.btn-primary:hover的background-color为var(--bs-primary)，避免它仍用编译时的#0d6efd - 表单聚焦边框：
.form-control:focus的border-color改为var(--bs-primary)，否则暗黑模式下可能还是亮色边框 - 禁用态文本：
.btn:disabled的color应设为var(--bs-body-color)而非固定#6c757d，否则在深色背景下不可读
示例补丁：
.btn-primary {
background-color: var(--bs-primary);
border-color: var(--bs-primary);
}
.btn-primary:hover {
background-color: var(--bs-primary);
}
.form-control:focus {
border-color: var(--bs-primary);
box-shadow: 0 0 0 0.25rem rgba(var(--bs-primary-rgb), 0.25);
}
用户手动切换时，如何避免闪屏和状态丢失
单纯靠 document.documentElement.classList.toggle('dark') 会导致页面先渲染亮色再切暗色，尤其在慢设备上明显。更关键是：切换后 prefers-color-scheme 监听器不会触发，用户下次刷新页面又回到系统偏好。
- 首次加载时，用
localStorage.getItem('theme')读取用户上次选择，比matchMedia优先级更高 - 在
中内联一段 JS，根据存储值提前设置html类，防止 FOUC - 监听
localStorage变化（用storage事件），实现多标签页同步 - 不要移除
prefers-color-scheme媒体查询 —— 它仍是兜底方案，比如用户清空 localStorage 后应恢复系统偏好
容易忽略的一点：Bootstrap 的 data-bs-theme="dark" 属性（用于部分组件如 tooltip）和你的 CSS 变量体系无关，必须统一收口到 class 切换逻辑中，否则会出现 tooltip 暗而按钮亮的割裂感。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
