必须在@import "bootstrap/scss/variables"前重定义$primary等变量，否则无效；正确顺序为先声明变量（推荐用!default），再依次导入functions、variables、bootstrap，并用map-merge增量扩展$theme-colors且显式调用@include theme-colors()。
必须在 @import "bootstrap/scss/variables" 之前重定义变量，否则所有修改都无效——Sass 变量只在首次声明时生效，后续赋值被静默忽略。
为什么改了 $primary 却没变色？
常见错误是把变量写在 Bootstrap 源文件导入之后。比如：
@import "bootstrap/scss/bootstrap"; $primary: #dc2626; // ❌ 完全无效，variables 已加载完毕
真正起作用的顺序必须是：
- 先声明变量（带
!default更安全） - 再依次
@import "bootstrap/scss/functions"、@import "bootstrap/scss/variables"、@import "bootstrap/scss/bootstrap" - 确保你的构建入口是你自己的
custom.scss，而不是直接引用bootstrap.min.css
漏掉 functions 会导致编译报错 Undefined variable: "$font-size-base"；顺序颠倒会让 $primary-rgb 等衍生变量仍用默认值。
立即学习“前端免费学习笔记（深入）”；
如何安全新增一个主题色（如 navy）？
不能直接写 $theme-colors: ("navy": #0f766e)，这会清空 primary、success 等所有内置键，导致 .btn-secondary 失效。
正确做法是用 map-merge() 增量添加，并显式调用 @include theme-colors()：
$navy: #0f766e;
$theme-colors: map-merge($theme-colors, ("navy": $navy));
@include theme-colors();
注意："navy" 必须是字符串，navy（无引号）会编译失败；@include theme-colors() 必须放在所有 @import 之后，且已导入 bootstrap/scss/utilities 或至少 bootstrap/scss/utilities/api。
DevTools 里查不到 .text-navy？大概率是 theme-colors() 没执行，或 utilities 根本没引入。
哪些变量能改？哪些改了也白改？
$primary、$font-size-base、$border-radius 这类语义变量可安全覆盖；但以下情况改了也没用：
- 在
:root里重写--bs-primary：这只是编译时生成的“快照”，不影响lighten($primary, 10%)这类 Sass 函数产出的样式 - 试图用 JS 动态改
document.documentElement.style.setProperty('--bs-primary', 'red')：同样只影响直接读取该 CSS 变量的地方，大量组件样式早已固化 - 把变量塞进
node_modules/bootstrap/scss/_variables.scss：下次yarn upgrade就丢，且违反不可变依赖原则
真正生效的前提只有一个：你修改的是参与构建的 Sass 源。
自定义容器宽度或断点时容易踩的坑
改 $container-max-widths 时必须同步调整 $grid-breakpoints，否则断点类（如 .container-lg）和实际容器宽度不匹配。比如把 xl 断点从 1140px 改成 1200px，但忘了改 $container-max-widths 里的 xl 值，结果 .container-xl 宽度还是旧的。
同理，改 $grid-breakpoints 后，$navbar-breakpoint、$offcanvas-breakpoint 这些组件专属断点变量也要手动覆盖——它们不会自动响应 $grid-breakpoints 的变化。
新增断点（如 "2xl"）后，$container-max-widths 和 $grid-breakpoints 的键名、顺序、单位（必须是 px）必须完全一致，否则 col-2xl-4 这类类名根本不会被编译出来。
