本文系统梳理 SCSS 变量无法生效的六大典型原因（路径错误、@import废弃、作用域污染、构建链路错配等），详解 @use + additionalData + :export 三位一体的现代解决方案，并提供 Vite/Bootstrap/uni-app 多环境可落地配置示例。
本文系统梳理 scss 变量无法生效的六大典型原因（路径错误、`@import`废弃、作用域污染、构建链路错配等），详解 `@use` + `additionaldata` + `:export` 三位一体的现代解决方案，并提供 vite/bootstrap/uni-app 多环境可落地配置示例。
在 SCSS 开发中，像 $deepBlue: #032f3e; 这样的变量在 .scss 文件中定义后却无法在样式规则中使用（如 background-color: $deepBlue; 报 Undefined variable），是高频且令人困惑的问题。根本原因并非语法错误，而是 SCSS 模块系统演进与构建工具链不匹配所致——尤其当项目混合了 Bootstrap 5.3.3 等依赖 @import 的旧库时，冲突尤为明显。
? 核心原则：@import 已淘汰，@use 是唯一正解
Dart Sass 1.70.0+ 默认禁用 @import，所有变量、mixin、function 不再自动注入全局作用域。你当前代码中的：
@import "../node_modules/bootstrap/scss/bootstrap";
不仅无法让 $deepBlue 生效，还会因 Bootstrap 内部仍含 @import 调用而触发编译失败（需显式启用 --load-path 或改用兼容模式）。正确做法是：
✅ 统一使用 @use 显式导入并控制命名空间
立即学习“前端免费学习笔记（深入）”；
// custom.scss —— 唯一应被构建工具编译的入口文件
@use "sass:math"; // 如需除法运算
@use "@/styles/variables" as *; // 导出所有变量到当前作用域
@use "../node_modules/bootstrap/scss/functions" as bs-fn;
@use "../node_modules/bootstrap/scss/variables" as bs-var;
@use "../node_modules/bootstrap/scss/mixins" as bs-mix;
@use "../node_modules/bootstrap/scss/root";
@use "../node_modules/bootstrap/scss/reboot";
@use "../node_modules/bootstrap/scss/type";
// ✅ 现在可安全使用自定义变量
body {
background-color: $deepBlue; // ← 正确！
--bs-body-bg: $deepBlue; // ← 同时导出为 CSS 变量供 JS 动态读写
}⚙️ 构建工具配置关键点（以 Vite 为例）
若在 <style lang="scss"></style> 中直接使用变量，必须通过 additionalData 注入，而非在 HTML 中引入 .scss 源文件（HTML 只能加载已编译的 .css）：
// vite.config.ts
export default defineConfig({
css: {
preprocessorOptions: {
scss: {
// 注意：结尾必须有分号，路径需被 resolve.alias 支持
additionalData: '@use "@/styles/variables.scss" as *;'
}
}
},
resolve: {
alias: {
'@': path.resolve(__dirname, 'src')
}
}
})⚠️ 错误示范（导致变量失效）：
- 在 HTML 中
<link href="./node_modules/bootstrap/scss/bootstrap.scss">→ 浏览器无法解析 SCSS - 使用
prependData（Vite 已废弃）→ 配置被忽略 -
additionalData中混用@import→ Dart Sass 直接报错
? Bootstrap 5.3.3 定制化最佳实践
Bootstrap 官方明确要求 覆盖变量必须在 @use 之前完成：
// custom.scss
// Step 1: 覆盖 Bootstrap 变量（必须在 @use 之前！）
$primary: #032f3e !default;
$body-bg: #f8f9fa !default;
// Step 2: 导入 Bootstrap 模块（推荐按需引入）
@use "../node_modules/bootstrap/scss/functions";
@use "../node_modules/bootstrap/scss/variables";
@use "../node_modules/bootstrap/scss/mixins";
@use "../node_modules/bootstrap/scss/root";
@use "../node_modules/bootstrap/scss/reboot";
@use "../node_modules/bootstrap/scss/type";
@use "../node_modules/bootstrap/scss/buttons";
// Step 3: 自定义样式（此时 $primary 已生效）
.btn-custom {
background-color: $primary; // ← Bootstrap 覆盖值生效
&:hover { background-color: darken($primary, 10%); }
}? 进阶：跨语言共享变量（JS ↔ SCSS）
若需在 JS 中读取 $deepBlue（如主题切换），使用 :export：
// styles/variables.scss
$deepBlue: #032f3e;
:export {
deepBlue: #{$deepBlue}; // 必须用插值 #{} 输出字符串
}// main.ts
import theme from './styles/variables.scss';
document.documentElement.style.setProperty('--bs-body-bg', theme.deepBlue);✅ 最终检查清单
- [ ] 删除所有
@import，全部替换为@use "path" as *; - [ ] 确保
additionalData配置在vite.config.ts中且路径可解析 - [ ] HTML 中只引用编译后的
custom.css，绝不引用.scss源文件 - [ ] Bootstrap 变量覆盖写在
@use语句之前 - [ ] 使用
sass（非node-sass或sass-embedded）作为预处理器依赖 - [ ] 运行
npm ls sass确认其位于devDependencies
遵循此方案，$deepBlue 将在所有 SCSS 上下文中稳定可用，同时保持与 Bootstrap 5.3.3 的完全兼容性。记住：SCSS 变量是编译期契约，而 CSS 变量才是运行时桥梁——二者协同，而非替代。
