必须在导入 Bootstrap 的 functions 和 variables 前重定义 $grid-breakpoints，同步更新 $container-max-widths 等关联变量，确保键名合法、升序排列且完整，否则断点不生效或组件行为异常。
如何修改 $grid-breakpoints 变量来新增或调整断点
Bootstrap 5 的响应式栅格系统依赖于 $grid-breakpoints 这个 Sass map 变量，它定义了所有断点的名称和对应最小宽度值。直接覆盖这个变量是唯一可靠的方式——不能只改单个 $container-max-widths 或单独重写媒体查询。
常见错误是只在 CSS 中加媒体查询，结果 col-md-6、px-lg-4 等类名不生效，因为这些工具类的生成逻辑完全由 $grid-breakpoints 驱动。
- 在自定义 Sass 文件（如
_custom.scss）顶部，先@importBootstrap 的变量文件：@import "bootstrap/scss/functions"; @import "bootstrap/scss/variables"; - 紧接着重新定义
$grid-breakpoints，例如增加一个xl断点并调整lg：$grid-breakpoints: ( xs: 0, sm: 576px, md: 768px, lg: 992px, xl: 1200px, xxl: 1400px );
- 必须在
@import "bootstrap/scss/maps"和@import "bootstrap/scss/mixins"之前完成赋值，否则后续 map 合并会失效
为什么必须同步更新 $container-max-widths 和 $grid-columns
只改断点会导致容器宽度错位、栅格列数异常：比如你新增了 xxl，但 $container-max-widths 里没配对应宽度，.container 在该断点下仍按 xl 宽度渲染；若 $grid-columns 仍为 12，而你期望在 xxl 下用 16 列布局，col-xxl-4 就不会生成。
-
$container-max-widths必须与$grid-breakpoints键名严格一致，缺失键将回退到上一个断点的值 - 如果只希望扩展断点而不改列数，可复用原
$grid-columns值；若需不同列数，需同时覆盖$grid-columns并确保bootstrap/scss/grid被引入 - 示例（接上文）：
$container-max-widths: ( xs: 100%, sm: 540px, md: 720px, lg: 960px, xl: 1140px, xxl: 1320px );
编译时遇到 Invalid CSS after "...-breakpoints: (": expected expression 怎么办
这个错误几乎全是 Sass 版本或语法细节导致的。Bootstrap 5.3+ 要求使用 Dart Sass ≥ 1.33，Node Sass 已废弃且不兼容新 map 写法。
立即学习“前端免费学习笔记（深入）”；
- 检查
sass --version输出是否为 Dart Sass（不是 Node Sass 或 Legacy Ruby Sass） - 确认所有 map 键名后有冒号，且末尾无逗号（Dart Sass 对 trailing comma 敏感）：
xl: 1200px✅，xl: 1200px,❌ - 确保没有在
$grid-breakpoints定义前意外引入了bootstrap/scss/bootstrap全量文件——它会立即消费未覆盖的原始变量 - 若用 Webpack + sass-loader，检查
additionalData是否把变量注入到了每个文件开头，造成重复定义
生成的 CSS 里断点类名没出现？检查 @import 顺序和模块依赖
即使变量改对了，col-xxl-6、d-xxl-block 等类名没生成，大概率是核心模块没被正确触发。Bootstrap 的工具类（utilities）和栅格（grid）都依赖 maps 和 mixins，而这两者又依赖已更新的 $grid-breakpoints。
- 你的主 SCSS 文件中，
@import顺序必须是：functions→variables→ **你的自定义变量** →maps→mixins→utilities→grid - 不要跳过
@import "bootstrap/scss/maps";—— 它内部会基于你改过的$grid-breakpoints生成$grid-breakpoint-names等派生变量 - 如果用的是 Bootstrap 官方 npm 包，路径必须写全：
bootstrap/scss/xxx，不能简写成bootstrap/xxx，否则可能加载到内置 CSS 而非源码
最易忽略的一点：所有断点相关类名（包括 gutter、gap、text-breakpoint）都共享同一套断点定义。改一处，全链路生效，但也意味着漏掉任一环节，整条链就断了。
