Ошибка валидации схемы css-loader — одна из самых частых причин сбоев сборки Webpack: она срабатывает до начала компиляции и выдаёт путь ошибки, который выглядит загадочно, пока вы не научитесь его читать. Это руководство объясняет, что именно вызывает эти ошибки, как расшифровать сообщение, какие изменения в webpack.config.js исправляют каждый случай и как проверить конфигурацию, чтобы следующая сборка прошла с первого раза.
Что такое ошибка валидации схемы?
Webpack проверяет объект опций каждого лоадера по JSON-схеме до начала компиляции. Схема определяет, какие свойства разрешены, какие типы они принимают и какие значения допустимы. Когда ваша конфигурация передаёт свойство, которое схема не распознаёт, — или передаёт неверный тип для известного свойства, — Webpack выбрасывает ошибку валидации схемы и отказывается собирать.
Почему валидация происходит до компиляции
Webpack проверяет заранее, потому что опции лоадеров влияют на обработку файлов. Неверная опция могла бы тихо выдать неправильный результат, если бы Webpack её игнорировал, поэтому строгая валидация при старте — более безопасное решение. Обратная сторона — жёсткая остановка до всякого кода, но сообщение об ошибке всегда точно говорит, какая опция неверна и где она находится в дереве конфигурации.
Формат ошибки
Ошибка валидации схемы css-loader имеет предсказуемую структуру. Она всегда содержит имя лоадера (css-loader), путь к проблемной опции в вашем объекте конфигурации (например, options.localIdentName), конкретную проблему (`неизвестное свойство, должно быть одним из допустимых значений или должно быть [тип]`) и часто ссылку на документацию лоадера. Сначала прочитать путь — всегда самый быстрый путь к исправлению.
Note
Почему их вызывает css-loader
css-loader пережил значительные изменения схемы опций между мажорными версиями. Разработчики, обновляющие css-loader — или копирующие webpack.config.js из туториала для другой версии, — часто получают опции, которые были валидны в старом релизе, но теперь неизвестны или реорганизованы.
Все опции CSS Modules перенесены под опцию modules, чтобы избежать загрязнения опций верхнего уровня и повысить ясность схемы.
Ломающее изменение v4
Самый частый источник ошибок схемы css-loader — миграция v3 → v4. В css-loader v3 опции CSS Modules находились на верхнем уровне объекта опций: localIdentName, camelCase, minimize и modules как булево значение. В v4 все опции CSS Modules переехали в отдельный подобъект modules, а minimize была полностью удалена (минификация CSS теперь относится к css-minimizer-webpack-plugin). Любой проект, всё ещё использующий плоский синтаксис v3 с установкой v4+, немедленно получает ошибку валидации схемы.
Другие частые причины
- Опечатки в именах опций - moduls вместо modules, localIdentiyName вместо localIdentName
- Неверный тип значения - строка там, где требуется объект, или число там, где ожидается булево значение
- Удалённые опции - minimize (удалена в v4), importLoaders как булево значение (должно быть числом), camelCase (удалена в v6)
- Копирование конфигов из туториалов другой версии - ответы Stack Overflow для css-loader v2 до сих пор массово выдаются поисковиками
- Конфликтующие peer-зависимости - сторонний пакет закрепляет старую версию css-loader, несовместимую с вашей конфигурацией
Tip
Чтение сообщения об ошибке
Каждая ошибка валидации схемы css-loader содержит информацию, нужную для её исправления — если вы умеете читать нотацию путей. В сообщении важны три части: имя лоадера, путь конфигурации и конкретное описание проблемы. Сосредоточьтесь на них именно в этом порядке.
Понимание нотации путей
Нотация путей отражает структуру вашего webpack.config.js. Путь вроде module.rules[0].use[1].options.localIdentName означает: посмотрите ключ module, затем rules, затем первый элемент массива (индекс 0), затем use, затем второй лоадер в этом массиве use (индекс 1), затем options и затем свойство localIdentName. Следуйте этому пути в файле конфигурации, чтобы найти точную строку, вызывающую ошибку.
Три подтипа ошибок
| Подтип ошибки | Сообщение содержит | Что это значит | Исправление |
|---|---|---|---|
| Неизвестное свойство | "has an unknown property" | Свойства нет в этой версии | Удалить или переименовать свойство |
| Неверный тип | "should be a [type]" | Верное свойство, неверный тип значения | Привести значение к правильному типу |
| Недопустимое значение | "should be one of the allowed" | Верное свойство, значение вне разрешённого набора | Использовать одно из перечисленных допустимых значений |
| Дополнительное свойство | "additionalProperties is false" | В объекте есть ключи вне схемы | Удалить неперечисленные ключи из объекта |
Подтип «должно быть одним из допустимых» всегда перечисляет корректные опции прямо в ошибке. Подтип «неизвестное свойство» не предлагает альтернатив — нужно свериться с актуальной документацией css-loader для нового имени или эквивалента свойства. Используйте Валидатор Конфигурации Webpack, чтобы получить все ошибки сразу, а не открывать их по одной через повторные сборки.
Warning
Как исправить ошибки css-loader
Исправление — всегда точечное изменение объекта опций css-loader в вашем webpack.config.js. Пройдите эти шаги по порядку, чтобы устранить ошибку аккуратно, не внеся новых.
Прочитайте полное сообщение об ошибке и скопируйте путь
Пролистайте stack trace до секции ValidationError и скопируйте полное сообщение. В нём назван лоадер (css-loader), точный путь конфигурации и проблема. Путь указывает, какая запись rules и какая позиция в массиве use содержит недопустимый объект опций.
Найдите правило в webpack.config.js
Найдите запись module.rules, которая загружает файлы .css. Обычно это test для .css-файлов с style-loader и css-loader и объектом опций. Объект опций внутри записи css-loader — источник всех ошибок схемы. Откройте этот объект и сравните его со списком допустимых опций вашей установленной версии css-loader.
Примените правильное исправление для вашего подтипа ошибки
Для ошибки неизвестное свойство: переименуйте или переместите свойство на новое место. localIdentName становится modules.localIdentName. minimize удалена — установите css-minimizer-webpack-plugin отдельно. camelCase удалена — используйте вместо неё опцию exportLocalsConvention в объекте modules. Для ошибки неверный тип: преобразуйте modules: true в объект с mode: 'local', если вам нужна конфигурация CSS Modules, или оставьте булевым, если нет.
Проверьте исправленную конфигурацию перед пересборкой
Вставьте обновлённый webpack.config.js в Валидатор Конфигурации Webpack, чтобы убедиться, что все ошибки схемы устранены, перед запуском полной сборки. Это ловит вторичные ошибки, внесённые исправлением, и экономит ещё один цикл сборки.
Валидатор Конфигурации Webpack
Вставьте свой webpack.config.js и мгновенно проверьте все опции лоадеров — обнаруживает ошибки схемы css-loader, недопустимые правила модулей и ошибки конфигурации вывода до следующей сборки.
Частые ошибки конфигурации css-loader
Это конкретные ошибки опций, которые чаще всего встречаются в сбоях валидации схемы css-loader. Каждая запись показывает сломанный шаблон конфигурации, правильную замену и версию css-loader, к которой относится изменение.
localIdentName на верхнем уровне (v3 → v4)
В css-loader v3 localIdentName был опцией верхнего уровня, управлявшей генерацией имён классов CSS Modules. В v4+ он переместился внутрь объекта modules. Исправление — вложить его в modules с заданным вашим шаблоном свойством localIdentName. Сообщение об ошибке гласит options has an unknown property 'localIdentName' — это ошибка миграции css-loader номер один.
Опция minimize удалена (v4+)
Опция minimize была удалена из css-loader в v4. Минификацией CSS теперь отдельно занимается css-minimizer-webpack-plugin в массиве optimization.minimizer. Полностью уберите minimize из опций css-loader и добавьте css-minimizer-webpack-plugin в сборку, если минификация нужна. Валидатор CSS поможет убедиться, что итоговый CSS корректен после смены инструмента минификации.
Опция camelCase удалена (v6)
css-loader v6 удалил опцию camelCase верхнего уровня. Замена — modules.exportLocalsConvention, которая принимает camelCase, camelCaseOnly, dashes или dashesOnly. Обновите опции, задав exportLocalsConvention внутри объекта modules. Без этого изменения любая установка v6 со старым свойством camelCase выдаст ошибку неизвестного свойства.
| Старая опция (сломана) | Версия css-loader | Правильная замена |
|---|---|---|
| options.localIdentName | v4+ | options.modules.localIdentName |
| options.minimize | v4+ | плагин css-minimizer-webpack-plugin |
| options.camelCase | v6+ | options.modules.exportLocalsConvention |
| options.modules: true | v4+ (для настройки) | options.modules: { mode: "local", ... } |
| options.importLoaders: true | все | options.importLoaders: 1 (число, не булево значение) |
| options.sourceMap: "inline" | v4+ | options.sourceMap: true (только булево значение) |
Note
Валидация конфигурации webpack
Самый эффективный способ устранить ошибки схемы css-loader — особенно после мажорного обновления — это проверить весь webpack.config.js сразу, а не обнаруживать ошибки по одной сборке за раз. Несколько инструментов ускоряют это.
Валидатор Конфигурации Webpack
Валидатор Конфигурации Webpack принимает ваш полный webpack.config.js и сообщает обо всех нарушениях схемы по каждому лоадеру, плагину и опции верхнего уровня за один проход. Он показывает ту же нотацию путей, которую Webpack использует в ошибках времени выполнения, поэтому вывод можно сверить с ошибкой из терминала. Вставьте конфигурацию, получите все проблемы сразу, исправьте их и вставьте снова для подтверждения — цикл сборки не нужен.
Сначала проверить файл конфигурации на синтаксические ошибки JavaScript
Если Webpack не может даже распарсить ваш webpack.config.js из-за синтаксической ошибки JavaScript — непарные скобки, пропущенная запятая или неверный spread — вы увидите ошибку парсинга Node.js, а не ошибку валидации схемы. Используйте Валидатор Синтаксиса JavaScript, чтобы исключить проблемы синтаксиса до отладки валидации схемы.
Проверка связанных файлов конфигурации
css-loader редко бывает единственным файлом конфигурации в сборочном конвейере. Если вы используете PostCSS для трансформаций, Валидатор Конфигурации PostCSS выявляет ошибки порядка плагинов и отсутствующие зависимости в postcss.config.js. Если вы используете stylelint для контроля качества CSS, Валидатор Конфигурации Stylelint проверит ваш .stylelintrc до того, как он помешает сборке. Валидатор Конфигурации ESLint полезен, если ваша сборочная цепочка также запускает ESLint — неверные конфигурации там могут проявляться как ошибки сборки, похожие на ошибки лоадеров.
Валидатор Конфигурации PostCSS
Проверяйте postcss.config.js на ошибки порядка плагинов и опций — обнаруживает проблемы конфигурации, которые часто сопровождают ошибки схемы css-loader в сложных настройках Webpack.
css-loader с PostCSS и CSS Modules
Большинство продакшн-настроек Webpack используют css-loader вместе с PostCSS и CSS Modules. Каждый добавляет свои опции и свои потенциальные ошибки схемы. Понимание их взаимодействия предотвращает самые частые конфликты конфигурации.
Опция importLoaders
Когда PostCSS обрабатывает CSS-файл до css-loader, вы должны задать importLoaders: 1 (или больше) в опциях css-loader, чтобы @import-инструкции в CSS тоже обрабатывались PostCSS. Без этого импортируемые файлы минуют PostCSS. Частая ошибка — importLoaders: true — вызывает ошибку валидации схемы, потому что опция должна быть числом, а не булевым значением. Установите её равной числу лоадеров, которые в цепочке идут до css-loader.
CSS Modules с пользовательскими именами классов
Кастомизация имён классов CSS Modules переехала в подобъект modules в css-loader v4. Полная конфигурация CSS Modules с пользовательским шаблоном идентификаторов использует mode, localIdentName и exportLocalsConvention — каждое как отдельная опция со своими ограничениями схемы. Передача любого из них на верхнем уровне options вместо modules приводит к ошибке неизвестного свойства.
Опции url и import
Опции url и import в css-loader управляют тем, разрешает ли лоадер ссылки url() и инструкции @import. Обе принимают либо булево значение, либо объект с функцией-фильтром. Передача простой функции — вместо объекта со свойством filter — вызывает ошибку схемы, поскольку схема опции ожидает объект со свойством filter, а не «голую» функцию. Всегда оборачивайте функции-фильтры в ожидаемую форму объекта.
Warning
Key takeaways
- Ошибки валидации схемы css-loader срабатывают до компиляции и всегда называют точный путь недопустимой опции — сначала читайте путь, а не stack trace.
- Самая частая причина — использование синтаксиса опций css-loader v3 (плоский localIdentName, minimize, camelCase) с установкой v4+ или v6+.
- В css-loader v4+ все опции CSS Modules переезжают в подобъект modules — localIdentName становится modules.localIdentName.
- minimize удалена в v4 — используйте вместо неё css-minimizer-webpack-plugin в optimization.minimizer.
- importLoaders должно быть числом (например, 1), а не булевым значением — передача true вызывает ошибку валидации типа.
- Используйте Валидатор Конфигурации Webpack, чтобы поймать все ошибки схемы за один проход перед пересборкой.
- Проверяйте и связанные конфиги — неверные конфигурации PostCSS, ESLint и Stylelint часто сопровождают ошибки css-loader в сложных конвейерах.