Исправление ошибки 'Undefined variable' в Sass @use: Полное руководство

Ошибка “Undefined variable” в системе модулей @use Sass

Ошибка “Undefined variable” в системе модулей @use Sass обычно возникает, несмотря на правильный порядок импорта, из-за нескольких распространенных проблем. Наиболее вероятные причины: символы BOM в файлах, проблемы с кэшем компилятора, неправильная конфигурация модулей или определенные настройки компиляции Sass, которые влияют на видимость переменных.

Содержание

• Распространенные причины ошибок “Undefined variable” в @use
• Символы BOM и проблемы кодировки файлов
• Проблемы с кэшем компилятора
• Проблемы конфигурации модулей
• Расширенные шаги по устранению неполадок
• Стратегии предотвращения

Распространенные причины ошибок “Undefined variable” в @use

Даже при правильном порядке импорта несколько технических проблем могут привести к тому, что Sass не сможет распознать определенные переменные:

1. Неявное против явной загрузки модулей

Ваш код использует @use 'base/variables' as *;, что должно правильно работать для импорта всех переменных. Однако убедитесь, что нет конфликтов с другими методами импорта, такими как @import, которые иногда могут создавать проблемы с областью видимости переменных.

2. Затенение переменных (Variable Shadowing)

Если одно и то же имя переменной определено в нескольких импортированных модулях, Sass может столкнуться с конфликтами. В вашем случае проверьте, определена ли переменная $font-family где-либо еще в вашем проекте или не переопределяется ли она.

3. Проблемы в конвейере компиляции

Современные инструменты сборки, такие как Vite, Webpack или Gulp, могут иметь собственную конфигурацию Sass, которая влияет на обработку модулей. То, что ошибка возникает в разных файлах, указывает на то, что это может быть проблема конвейера компиляции, а не чисто проблема Sass.

Символы BOM и проблемы кодировки файлов

Символы Byte Order Mark (BOM) являются частой причиной ошибок “Undefined variable” в Sass.

Обнаружение и удаление

# Проверьте наличие символов BOM в вашем файле переменных
file -bi styles/base/_variables.scss
# Должно вернуть: text/plain; charset=utf-8

# Используйте текстовый редактор, например VS Code:
# 1. Откройте _variables.scss
# 2. Сохранить с кодировкой → Сохранить с кодировкой → UTF-8 (без BOM)

Проверка кодировки файла

Убедитесь, что все ваши файлы Sass используют кодировку UTF-8 без BOM. В VS Code:

• Откройте палитру команд (Ctrl+Shift+P)
• Найдите “Сохранить с кодировкой”
• Выберите “UTF-8 без BOM”

Проблемы с кэшем компилятора

Компиляторы Sass поддерживают кэш, который может повредиться, что приводит к непоследовательному поведению.

Решения по очистке кэша

Для Sass CLI:

# Очистка кэша Sass
rm -rf .sass-cache/
# Или для конкретного проекта
npx sass --no-source-map --no-unicode styles/main.scss dist/main.css --no-cache

Для инструментов сборки на Node.js:

# Если используется node-sass или пакет sass
rm -rf node_modules/.cache/
rm -rf .next/  # Если используется Next.js
rm -rf .vuepress/  # Если используется VuePress

Для режима Live Reload/Watch:

# Полностью остановите процесс отслеживания изменений
# Перезапустите сервер разработки
# Выполните чистую сборку перед перезапуском

Проблемы конфигурации модулей

1. Конфигурация путей загрузки

Убедитесь, что ваш инструмент сборки включает правильные пути загрузки для модулей Sass:

Пример конфигурации Webpack:

module.exports = {
  module: {
    rules: [
      {
        test: /\.s[ac]ss$/i,
        use: [
          'style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              sassOptions: {
                includePaths: ['styles'] // Добавьте вашу директорию со стилями
              }
            }
          }
        ]
      }
    ]
  }
};

Конфигурация Vite:

// vite.config.js
export default {
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "@/styles/base/variables.scss";`,
        sassOptions: {
          includePaths: ['src/styles']
        }
      }
    }
  }
}

2. Проблемы с расширениями файлов

Некоторые инструменты сборки требуют определенных расширений файлов или конфигураций:

// Попробуйте явное расширение .scss, если не работает
@use 'base/variables.scss' as *;
@use 'base/typography.scss';

Расширенные шаги по устранению неполадок

1. Изоляция проблемы

Создайте минимальный тестовый случай для изоляции проблемы:

// test.scss
@use 'base/variables' as *;

body {
  font-family: $font-family; // Работает ли это?
}

// test-variables.scss
$font-family: 'Test Font', sans-serif;

2. Отладка доступа к переменным

Добавьте вывод отладки для проверки загрузки переменных:

@use 'base/variables' as *;

// Отладка: Проверьте, загружены ли переменные
@debug 'Variables loaded:';
@debug $font-family;
@debug $header-bg;

body {
  font-family: $font-family;
}

3. Альтернативные методы импорта

Попробуйте разный синтаксис импорта для выявления проблемы:

// Метод 1: Явное пространство имен
@use 'base/variables';
body {
  font-family: variables.$font-family;
}

// Метод 2: Псевдоним пространства имен
@use 'base/variables' as vars;
body {
  font-family: vars.$font-family;
}

// Метод 3: Традиционный @import (только для теста)
@import 'base/variables';
body {
  font-family: $font-family;
}

4. Проверка версии компилятора

Убедитесь, что вы используете совместимую версию Sass:

sass --version
# Должна быть 1.23.0 или выше для поддержки @use

Обновите при необходимости:

npm install sass@latest --save-dev

Стратегии предотвращения

1. Лучшие практики структуры файлов

styles/
├── base/
│   ├── _variables.scss      # Сначала все переменные
│   ├── _mixins.scss         # Затем миксины
│   ├── _functions.scss      # Затем функции
│   └── _typography.scss     # И наконец компоненты, которые их используют
├── components/
└── main.scss               # Порядок импорта имеет значение

2. Автоматизированная проверка качества

Добавьте хуки pre-commit для обнаружения проблем кодировки:

// .huskyrc или скрипты в package.json
{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "*.scss": ["sass-lint --fix", "git add"]
  }
}

3. Проверка конфигурации сборки

Регулярно проверяйте вашу конфигурацию сборки:

# Тестовая компиляция Sass в изоляции
npx sass --no-source-map --no-unicode styles/main.scss --stdout

# Проверьте наличие предупреждений или ошибок
npx sass styles/main.scss dist/main.css --style=expanded --verbose

Источники

1. Документация Sass - Система модулей
2. Проблемы Sass на GitHub - Распространенные проблемы с переменными
3. Конфигурация VS Code для Sass
4. Документация Webpack Sass Loader
5. Опции CSS препроцессора в Vite

Заключение

Ошибка “Undefined variable” в системе @use Sass, несмотря на правильный порядок импорта, обычно вызвана одной из этих основных причин:

1. Символы BOM в ваших файлах - всегда сохраняйте с кодировкой UTF-8 без BOM
2. Поврежденный кэш компилятора - очистите .sass-cache и перезапустите процесс сборки
3. Проблемы конфигурации инструмента сборки - проверьте пути загрузки и разрешение модулей
4. Конфликты области видимости переменных - проверьте наличие дублирующихся определений переменных

Начните с проверки символов BOM и очистки кэша, так как это наиболее частые причины проблемы. Если проблема сохраняется, изолируйте ее с помощью минимального тестового случая и систематически попробуйте разные методы импорта. Всегда поддерживайте последовательную кодировку файлов и рассмотрите возможность добавления хуков pre-commit для предотвращения проблем с кодировкой в будущем.