Next.js集成DashUI模板遇Sass未定义变量错误求助

错误信息 #

SassError: Undefined variable.
   ╷
55 │     "primary": $primary-text-emphasis-dark,
   │                ^^^^^^^^^^^^^^^^^^^^^^^^^^^
   ╵
  node_modules/bootstrap/scss/_maps.scss 55:16  @import
  styles/theme/_utilities.scss 7:9              @import
  styles/theme.scss 29:9                        root stylesheet

将DashUI管理模板集成到Next.js应用时触发上述错误，但直接从GitHub克隆的模板代码单独运行完全正常，未修改任何代码，依赖版本也和原项目完全一致，需要排查问题原因并获取解决方向。

相关代码片段 #

node_modules/bootstrap/scss/_maps.scss 文件 #

@if $enable-dark-mode {
  // scss-docs-start theme-text-dark-map
  $theme-colors-text-dark: (
    "primary": $primary-text-emphasis-dark,
    "secondary": $secondary-text-emphasis-dark,
    "success": $success-text-emphasis-dark,
    "info": $info-text-emphasis-dark,
    "warning": $warning-text-emphasis-dark,
    "danger": $danger-text-emphasis-dark,
    "light": $light-text-emphasis-dark,
    "dark": $dark-text-emphasis-dark,
  ) !default;
  // scss-docs-end theme-text-dark-map

  // scss-docs-start theme-bg-subtle-dark-map
  $theme-colors-bg-subtle-dark: (
    "primary": $primary-bg-subtle-dark,
    "secondary": $secondary-bg-subtle-dark,
    "success": $success-bg-subtle-dark,
    "info": $info-bg-subtle-dark,
    "warning": $warning-bg-subtle-dark,
    "danger": $danger-bg-subtle-dark,
    "light": $light-bg-subtle-dark,
    "dark": $dark-bg-subtle-dark,
  ) !default;

_utilities.scss #

@import "~bootstrap/scss/functions";
@import "~bootstrap/scss/variables";
@import "~bootstrap/scss/maps";
@import "~bootstrap/scss/mixins";
@import "~bootstrap/scss/utilities";

theme.scss #

// Inter Fonts
@import url("https://fonts.googleapis.com/css2?family=Inter:wght@100;200;300;400;500;600;700;800;900&display=swap");

// Font Awesome
@import url("https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/all.css");

// Feathers CSS for Before Icon
@import url("/fonts/feather-icons/feather.css");

// Bootstrap functions
@import "~bootstrap/scss/functions";

// User Variables
@import "user-variables";

// theme variables
@import "theme/variables";

//utilities
@import "theme/utilities";

// Bootstrap
@import "~bootstrap/scss/bootstrap";

// Theme
@import "theme/theme";

// User
@import "user";

variables.scss 片段 #

$white: #fff !default;
$gray-100: #f1f5f9 !default;
$gray-200: #f4f6f8 !default;
$gray-300: #dfe3e8 !default;
$gray-400: #c4cdd5 !default;
$gray-500: #919eab !default;
$gray-600: #637381 !default;
$gray-700: #454f5b !default;
$gray-800: #212b36 !default;
$gray-900: #161c24 !default;
$black: #000 !default;
$red: #dc3545 !default;
$orange: #fd7e14 !default;
$yellow: #f59e0b !default;
$green: #198754 !default;
$teal: #20c997 !default;
$cyan: #0ea5e9 !default;
$primary: #624bff !default;
$secondary: $gray-600 !default;
$success: $green !default;
$info: $cyan !default;
$warning: $yellow !default;
$danger: $red !default;
$light: $gray-100 !default;
$dark: $gray-800 !default;

// Light color
$light-primary: #e0dcfe !default; // NEW
$light-secondary: #e9ecef !default; // NEW
$light-success: #eaf6ec !default; // NEW
$light-danger: #fbebec !default; // NEW
$light-warning: #fff3cd !default; // NEW
$light-info: #e7fafe !default; // NEW
$light-dark: #d1cfd8 !default; // NEW

// Dark color
$dark-primary: #593cc1 !default; // NEW
$dark-secondary: #5c596d !default; // NEW
$dark-success: #139a74 !default; // NEW
$dark-danger: #ae302e !default; // NEW
$dark-warning: #c28135 !default; // NEW
$dark-info: #51a0c2 !default; // NEW

$theme-colors: () !default;
$theme-colors: (
    "primary": $primary,
    "secondary": $secondary,
    "success": $success,
    "info": $info,
    "warning": $warning,
    "danger": $danger,
    "light": $light,
    "dark": $dark,
    "white": $white,
    "light-primary": $light-primary,
    "light-danger": $light-danger,
    "light-info": $light-info,
    "light-warning": $light-warning,
    "light-secondary": $light-secondary,
    "light-success": $light-success,
    "light-dark": $light-dark,
    "dark-primary": $dark-primary,
    "dark-warning": $dark-warning,
    "dark-info": $dark-info,
    "dark-danger": $dark-danger,
    "dark-success": $dark-success,
    "dark-secondary": $dark-secondary,
);

问题原因与解决步骤 #

核心原因 #

报错的$primary-text-emphasis-dark这类变量是Bootstrap暗黑模式的衍生变量，默认由Bootstrap内部函数基于自定义主题变量生成。当前错误是因为这些变量在_maps.scss被引用时还未生成，根源在于自有Next.js项目的Sass编译逻辑或导入优先级和原模板项目不一致：

• Next.js的Sass模块解析规则和原模板的构建工具（如Vite、Webpack）存在差异，导致~路径解析出错
• 导入流程中，Bootstrap的变量文件先于自定义主题变量生效，无法生成对应的暗黑模式衍生变量
• 暗黑模式默认开启，但衍生变量生成逻辑未被正确触发

解决步骤 #

1. 修正_utilities.scss的导入顺序

当前_utilities.scss直接导入Bootstrap文件，未先引入自定义主题变量，导致Bootstrap无法基于自定义值生成衍生变量。调整为：

// 先引入自定义主题变量，再加载Bootstrap文件
@import "../variables";
@import "~bootstrap/scss/functions";
@import "~bootstrap/scss/variables";
@import "~bootstrap/scss/maps";
@import "~bootstrap/scss/mixins";
@import "~bootstrap/scss/utilities";

2. 显式配置暗黑模式变量

在variables.scss末尾添加配置，确保衍生变量能正常生成：

// 显式开启暗黑模式
$enable-dark-mode: true !default;

// 手动生成暗黑模式文本强调变量（兜底方案）
@each $color, $value in $theme-colors {
  @if not map-has-key($theme-colors-text-dark, $color) {
    $#{$color}-text-emphasis-dark: theme-color-level($color, -9) !default;
  }
}

3. 配置Next.js的Sass解析路径

在next.config.js中添加Sass路径配置，确保自定义样式文件被正确识别：

const path = require('path');

module.exports = {
  sassOptions: {
    includePaths: [path.join(__dirname, 'styles')],
  },
};

4. 清理缓存并重装依赖

# 删除依赖包和锁文件
rm -rf node_modules package-lock.json yarn.lock
# 重新安装依赖
npm install
# 清理Next.js缓存并重新构建
npm run build --clean

内容的提问来源于stack exchange，提问作者Gilbert Intabo