<p>直接修改 :root 上的 --bs-* 变量最可靠，但必须同步更新所有链式依赖变量（如 --bs-primary 和 --bs-primary-rgb），否则派生样式会回退默认值；覆盖 .btn-primary 等 class 维护成本高、易遗漏、权重易被覆盖、Portal 渲染节点失效；Runtime 应用 document.documentElement.style.setProperty() 批量设置变量并确保 RGB 值准确；深色模式优先使用 data-bs-theme 属性而非手动切 class。</p>
直接改 :root 上的 --bs-* 变量最可靠，但必须同步更新所有链式依赖变量（比如改 --bs-primary 就得一起设 --bs-primary-rgb），否则阴影、透明边框等派生样式会 fallback 到默认值。
为什么不能只覆盖 .btn-primary 这类 class？
Bootstrap 5 的组件样式不是集中在一个 class 里，而是分散在多个地方：.btn-primary、.alert-primary、.form-check-input:checked、.list-group-item-primary……每个都要单独写规则，漏一个就失效。更麻烦的是，新版本加的组件你根本不知道要覆哪几个 class。
- 维护成本高：每次 Bootstrap 升级都得重新 audit 所有 class 选择器
- 权重易被压过：嵌套结构（如
.btn-group > .btn）特异性更高，你的.btn-primary规则常被划掉 - Portal 组件（tooltip/modal）渲染在
body底部，脱离原始 DOM，靠 class 覆盖极易失效
Runtime 修改 CSS Variables 的正确姿势
用 document.documentElement.style.setProperty() 设置 :root 变量，是唯一能穿透所有组件层级、包括 Portal 渲染节点的方式。
- 必须成对设置：改
--bs-primary就得同步设--bs-primary-rgb和--bs-primary-text-emphasis；查 Bootstrap 源码里的_variables.scss确认哪些变量引用了 RGB 值 - RGB 值别手算：比如
#6f42c1对应111, 66, 193，不是四舍五入后的111, 66, 192 - 避免用
cssText = ''覆盖整个 style 属性，会清空其他已设变量 - 推荐封装批量设置函数：
setBSVars({ '--bs-primary': '#6f42c1', '--bs-primary-rgb': '111, 66, 193' })
深色模式切换别手动切 class
不要自己加 className="dark" 再写一堆 .dark .btn 规则。Bootstrap 5.3+ 原生支持 data-bs-theme 属性：
立即学习“前端免费学习笔记（深入）”；
- 执行
document.documentElement.setAttribute('data-bs-theme', 'dark') - 对应变量由媒体查询或属性选择器自动替换（如
[data-bs-theme=dark] { --bs-primary: #0d6efd; }） - 所有组件立即响应，无需重写任何 CSS
最容易被忽略的是链式变量的完整性——哪怕只漏一个 --bs-*，比如 --bs-primary-rgb，就会导致 rgba(var(--bs-primary-rgb), .5) 计算失败，box-shadow 或半透明背景直接回退到蓝色默认值。调试时一定要在控制台展开 :root 元素，挨个确认所有相关变量是否都已更新。
