Bootstrap V5 从@import迁移到@use模块系统时出现Sass未定义mixin错误

AI 小北

2026-10-31

问题核心根因

Sass旧版@import采用全局作用域合并机制，所有引入的mixin、变量、函数都会被汇总到全局上下文，哪怕重复引入文件、依赖顺序不对，也很少立刻触发编译报错，这也是你之前旧写法能正常运行的原因
Sass新版@use采用模块隔离加载机制：每个引入的模块默认带独立命名空间，不会自动把内容暴露到全局，且同一个模块仅允许加载一次，模块之间的依赖有严格的加载顺序要求。你现在的写法刚好踩了两个适配坑：
- 冗余重复引入：~bootstrap/scss/bootstrap入口文件已经全量包含functions、variables、mixins模块的所有内容，额外重复引入这几个内部子文件，会触发Sass模块重复加载的异常，直接打乱模块上下文
- 作用域隔离识别失效：你没有按照@use的规则配置模块的暴露范围，调用Bootstrap内置mixin时，Sass在当前文件的作用域内找不到对应定义，就会抛出Undefined mixin的编译错误

可直接落地的解决步骤

1. 清理冗余的模块引入语句

完全不需要单独引入functions、variables、mixins这几个内部子文件，Bootstrap v5的入口文件已经完成了所有模块的依赖串联，基础引入的正确写法为：

// 引入Bootstrap核心模块，指定自定义命名空间避免和业务代码重名
@use "~bootstrap/scss/bootstrap" as bs;

如果需要自定义Bootstrap主题、覆盖默认变量，要严格按照加载顺序调整：必须在引入Bootstrap核心之前，先引入自定义变量覆盖模块，否则变量修改不会生效：

// 1. 优先引入自定义变量覆盖文件，暴露到当前作用域
@use "你的自定义变量文件路径" as *;
// 2. 再引入Bootstrap核心，此时Bootstrap会自动读取到前面覆盖的变量值
@use "~bootstrap/scss/bootstrap" as bs;

@use引入的模块默认不会把内容暴露到全局，如果你没有用as *指定全量暴露，调用Bootstrap内置mixin的时候必须带上对应命名空间，否则就会触发未定义报错：

旧@import时代的全局写法（直接不加前缀调用）：

.custom-card {
  @include media-breakpoint-up(md) {
    width: 80%;
  }
}

新@use时代的适配写法（带命名空间调用）：

.custom-card {
  // 这里的bs就是引入Bootstrap时指定的命名空间
  @include bs.media-breakpoint-up(md) {
    width: 80%;
  }
}

如果觉得每次写命名空间麻烦，可以在引入时指定as *，把Bootstrap的所有mixin、变量、函数直接暴露到当前文件作用域，就能和旧写法一样直接调用：

@use "~bootstrap/scss/bootstrap" as *;

// 下面的调用不需要加命名空间，和旧版写法完全一致
.custom-card {
  @include media-breakpoint-up(md) {
    width: 80%;
  }
}

⚠️ 注意：用as *暴露模块后，绝对不要再单独引入Bootstrap的内部子文件，否则会触发Sass模块重复加载规则，直接出现上下文混乱、未定义mixin的报错。

全量检查项目内的Sass文件，不要混用@import和@use语法，两种加载机制会互相打乱作用域上下文
检查本地Sass版本，低于1.33的旧版本对模块系统的支持不完善，建议升级到1.50以上的稳定版本再执行编译
不要单独引入Bootstrap的内部子模块（比如单独写@use "~bootstrap/scss/mixins"），这类内部文件依赖Bootstrap全局的变量、函数上下文，单独加载会因为找不到前置依赖直接触发报错

内容的提问来源于stack exchange，提问作者jhon-jhones