必须重编译Sass源码才能全局生效$primary变量；需在自定义入口文件顶部声明后引入Bootstrap，否则仅局部覆盖或完全无效。
修改 $primary 变量前必须重编译 Sass
bootstrap 5 的颜色变量定义在 _variables.scss 里，$primary 是一个 sass 变量，不是 css 自定义属性。直接改 css 文件或浏览器开发者工具里覆盖，只影响局部样式，且无法同步到所有依赖 $primary 的组件（比如 .btn-primary、.alert-primary、.border-primary）。必须从源码层面重定义并重新编译 sass 才能全局生效。
常见错误现象：
– 在 main.css 里写 .btn-primary { background-color: #ff6b35 !important; } → 按钮变色了，但 .text-primary 还是原来的蓝
– 把 $primary: #ff6b35; 写在引入 Bootstrap 之后的 CSS 文件里 → 完全无效，Sass 编译时早已解析完变量
- 正确做法：在自定义 Sass 入口文件（如
app.scss）顶部，先声明$primary: #ff6b35;，再@import "bootstrap/scss/bootstrap"; - 确保你用的是 Bootstrap 源码（
node_modules/bootstrap/scss/），不是已编译好的bootstrap.min.css - 如果用 Vite / Webpack / Laravel Mix，确认构建流程支持 Sass 编译；纯 HTML 引入 CDN 则无法实现
$primary 影响哪些组件和工具类
改了 $primary 不只是换按钮颜色，它会连锁影响整套语义化工具类和组件的默认样式生成逻辑。Sass 编译时，所有基于 $primary 衍生的颜色（如 lighten($primary, 10%)）、边框、阴影、文字、背景工具类，都会被重新计算。
典型受影响项：
– 工具类：.text-primary、.bg-primary、.border-primary、.link-primary、.shadow-primary（需启用对应模块）
– 组件：.btn-primary、.alert-primary、.progress-bar（当 value 达到最大时的填充色）、.list-group-item.active、.nav-link.active
- 注意
.btn-outline-primary的边框和文字色也由$primary决定，但背景是透明的，所以不会“变主色”，而是变轮廓色 - 如果同时修改了
$theme-colors映射（比如增加danger: #e74c3c），$primary仅控制 key 为primary的那一组，不影响其他主题色 - 某些深色模式相关变量（如
$primary-rgb）会自动从$primary解析，无需手动设置
用 map-merge 扩展 $theme-colors 更安全
直接覆盖 $primary 简单粗暴，但如果你还想保留原始 primary 含义（比如用于强调，但不想影响所有默认行为），或者想新增一套命名色（如 $brand），推荐用 map-merge 扩展 $theme-colors 并配合 !default 机制。
示例（放在 @import bootstrap 之前）：
$theme-colors: map-merge(
(
"primary": #ff6b35,
"secondary": #6c757d,
"success": #28a745
),
$theme-colors
);
- 这样既更新了
primary，又保留了 Bootstrap 原有其他颜色的默认值（因为$theme-colors本身带!default） - 避免遗漏：Bootstrap 5 中
$theme-colors默认包含primary到white共 11 个键，全量覆盖易出错；map-merge更精准 - 扩展后，
.text-brand、.bg-brand等工具类不会自动生成——要生成它们，得额外调用@include theme-colors()，否则只影响组件内部逻辑
检查是否漏掉 custom.scss 或缓存导致未生效
改完变量却没变化，大概率不是语法错，而是构建链路或缓存问题。Sass 编译失败时往往静默降级，不报错也不输出新 CSS。
- 确认你的入口 Sass 文件（如
app.scss）确实被构建工具监听并编译；删掉输出的app.css后重新运行命令，看是否重建 - 浏览器强刷（
Ctrl+Shift+R或禁用缓存调试），排除旧 CSS 缓存干扰 - 检查终端编译日志：Webpack 会显示
Compiled successfully，Vite 启动时有✓ 142 modules transformed类提示；如果无日志或报File to import not found，说明路径错了 - 路径常见错误：
@import "../node_modules/bootstrap/scss/bootstrap";（相对路径错）、@import "bootstrap/scss/bootstrap.scss";（多写了.scss后缀，Sass 不认）
真正麻烦的点不在怎么写变量，而在于确认整个 Sass 加载链是否完整跑通——变量改得再准，卡在上一步就没意义。
