Bootstrap 5 自定义 CSS 必须重写，因其变量体系、选择器权重、工具类逻辑和默认值全面变更，硬套 v4 样式会导致覆盖失效、断点错乱或响应式崩溃。
自定义 CSS 不能直接沿用，必须重写或重构——Bootstrap 5 的 CSS 变量体系、选择器权重、工具类生成逻辑和默认值都变了，硬套旧样式大概率导致覆盖失效、断点错乱或响应式崩溃。
为什么你的自定义 CSS 在 v5 中“突然不生效”
不是浏览器缓存问题，而是底层机制变了：
-
!important在 v5 中更容易被 CSS 变量（如--bs-body-font-size）和更深层的工具类覆盖，尤其在.form-control或.btn上叠加时 - v4 中靠
.my-2+ 自定义margin-top: 1rem能压住间距，v5 中.my-2是基于calc(var(--bs-spacer) * 0.5)计算的，而--bs-spacer默认是1rem，但如果你没同步更新$spacersSass map，实际值可能对不上 - 很多旧自定义样式依赖
.col-xs-6或.hidden-xs这类已彻底删除的类名，CSS 选择器直接失效，连警告都不会报
如何安全迁移 Sass 自定义变量
别只改单个变量，v5 的 Sass 体系是强关联的。例如你改了 $font-size-base，但没同步调整 $font-size-sm 和 $font-size-lg，.fs-sm 类就会缩放异常。
- 必须重载整个
$spacersmap：v4 是$spacer: 1rem; $spacers: ()，v5 要写成$spacers: (0: 0, 1: 0.25rem, 2: 0.5rem, ...)，漏一项，mt-3就可能变成mt-2的高度 -
$theme-colors现在是 map，且新增了primary-rgb等衍生变量；若你只加了custom: #333却没配custom-rgb，bg-custom在深色模式下会 fallback 到黑底白字，完全不可控 - 所有
@include混合宏签名变了：form-validation-state()现在要传四个参数（$state,$color,$icon,$tooltip），少一个就编译失败
纯 CSS 覆盖方案的三个实操底线
如果项目没用 Sass，只能写 CSS，那就得绕开 v5 的变量陷阱，用更确定的选择器锚定：
立即学习“前端免费学习笔记（深入）”；
- 避免用
.btn.btn-primary覆盖，改用button.btn.btn-primary:not([data-bs-toggle])—— 加上:not([data-bs-toggle])排除 JS 组件干扰，防止模态框触发按钮样式被误杀 - 不要写
.card .card-body { padding: 1.5rem }，v5 的.card-body默认 padding 已由--bs-card-cap-padding-y控制；应写.card > .card-body { padding: 1.5rem !important }，用子选择器+!important强制接管 - 自定义栅格偏移必须补全断点：
.offset-md-2在 v5 中不会自动降级到 xs，若你原来靠.offset-2（v4 写法）实现小屏偏移，现在得显式写.offset-0 .offset-sm-2 .offset-md-2
v5 的自定义难点不在“怎么写”，而在“写在哪一层”——Sass 变量、CSS 自定义属性、工具类、组件类，四层样式来源互相渗透。最容易被忽略的是：你改了一个 --bs-body-bg，但 .bg-body 类内部又用了 background-color: var(--bs-body-bg)，而 .card 的 background-color 又继承自 .bg-body……这种链式依赖，不画 DOM 树+CSS 层叠图，根本没法 debug。
