O erro de validação de esquema do css-loader é uma das falhas de build mais comuns do Webpack - ele dispara antes mesmo da compilação começar e apresenta um caminho de erro que parece críptico até você aprender a lê-lo. Este guia explica exatamente o que desencadeia esses erros, como decodificar a mensagem, quais mudanças no webpack.config.js corrigem cada caso e como validar sua configuração para que a próxima build funcione na primeira tentativa.
O que é um erro de validação de esquema?
O Webpack valida o objeto de opções de cada loader contra um esquema JSON antes de começar a compilar. Esse esquema define quais propriedades são permitidas, quais tipos aceitam e quais valores são válidos. Quando sua configuração passa uma propriedade que o esquema não reconhece - ou passa o tipo errado para uma propriedade conhecida - o Webpack lança um erro de validação de esquema e se recusa a compilar.
Por que a validação acontece antes da compilação
O Webpack valida com antecedência porque as opções dos loaders afetam como os arquivos são processados. Uma opção inválida poderia produzir silenciosamente uma saída errada se o Webpack a ignorasse, então a validação estrita na inicialização é o design mais seguro. A contrapartida é uma parada total antes de tocar em qualquer código - mas a mensagem de erro sempre diz exatamente qual opção está errada e onde ela está na sua árvore de configuração.
O formato do erro
Um erro de validação de esquema do css-loader segue uma estrutura previsível. Ele sempre inclui o nome do loader (css-loader), o caminho da opção problemática no seu objeto de configuração (ex. options.localIdentName), o problema específico (`propriedade desconhecida, deveria ser um dos valores permitidos ou deveria ser [tipo]`) e, com frequência, um link para a documentação do loader. Ler o caminho primeiro é sempre o caminho mais rápido para a correção.
Note
Por que o css-loader os dispara
O css-loader passou por mudanças significativas em seu esquema de opções entre versões maiores. Desenvolvedores que atualizam o css-loader - ou copiam um webpack.config.js de um tutorial voltado a outra versão - frequentemente acabam com opções que eram válidas em uma versão anterior, mas que agora são desconhecidas ou foram reestruturadas.
Todas as opções do CSS Modules foram movidas para dentro da opção modules para evitar poluição de opções no nível superior e melhorar a clareza do esquema.
A mudança disruptiva da v4
A fonte mais comum de erros de esquema do css-loader é a migração v3 → v4. No css-loader v3, as opções do CSS Modules ficavam no nível superior do objeto de opções: localIdentName, camelCase, minimize e modules como booleano. Na v4, todas as opções do CSS Modules foram movidas para um sub-objeto modules dedicado, e minimize foi removida por completo (a minificação de CSS agora pertence ao css-minimizer-webpack-plugin). Qualquer projeto que ainda use a sintaxe plana da v3 com uma instalação v4+ dispara imediatamente um erro de validação de esquema.
Outros gatilhos comuns
- Erros de digitação em nomes de opções - moduls em vez de modules, localIdentiyName em vez de localIdentName
- Tipo de valor errado - passar uma string onde um objeto é exigido, ou um número onde um booleano é esperado
- Opções removidas - minimize (removida na v4), importLoaders como booleano (deve ser um número), camelCase (removida na v6)
- Copiar configs de tutoriais de outra versão - respostas do Stack Overflow voltadas ao css-loader v2 ainda são amplamente servidas pelos buscadores
- Dependências peer conflitantes - um pacote de terceiros fixa uma versão antiga do css-loader incompatível com sua config
Tip
Lendo a mensagem de erro
Cada erro de validação de esquema do css-loader contém as informações de que você precisa para corrigi-lo - se souber ler a notação de caminhos. A mensagem tem três partes que importam: o nome do loader, o caminho de configuração e a descrição específica do problema. Foque nelas nessa ordem.
Entendendo a notação de caminhos
A notação de caminhos espelha a estrutura do seu webpack.config.js. Um caminho como module.rules[0].use[1].options.localIdentName significa: olhe a chave module, depois rules, depois o primeiro item do array (índice 0), depois use, depois o segundo loader desse array use (índice 1), depois options e depois a propriedade localIdentName. Siga esse caminho no seu arquivo de config para encontrar a linha exata que causa o erro.
Os três subtipos de erro
| Subtipo de erro | A mensagem contém | O que significa | Correção |
|---|---|---|---|
| Propriedade desconhecida | "has an unknown property" | A propriedade não existe nesta versão | Remova ou renomeie a propriedade |
| Tipo errado | "should be a [type]" | Propriedade certa, tipo de valor errado | Mude o valor para o tipo correto |
| Valor inválido | "should be one of the allowed" | Propriedade certa, valor fora do conjunto permitido | Use um dos valores válidos listados |
| Propriedade adicional | "additionalProperties is false" | O objeto tem chaves fora do esquema | Remova as chaves não listadas do objeto |
O subtipo «deveria ser um dos permitidos» sempre lista as opções válidas em linha no erro. O subtipo «propriedade desconhecida» não sugere alternativas - você precisa consultar a documentação atual do css-loader para o novo nome ou equivalente da propriedade. Use o Validador de Configuração Webpack para obter todos os erros de uma vez em vez de descobri-los um a um em builds repetidas.
Warning
Como corrigir erros do css-loader
A correção é sempre uma mudança direcionada no objeto de opções do css-loader no seu webpack.config.js. Siga estes passos em ordem para resolver o erro de forma limpa sem introduzir novos.
Leia a mensagem de erro completa e copie o caminho
Role além do stack trace até a seção ValidationError e copie a mensagem completa. Ela nomeia o loader (css-loader), o caminho exato de configuração e o problema. O caminho indica qual entrada de rules e qual posição do array use contém o objeto de opções inválido.
Localize a regra no webpack.config.js
Encontre a entrada module.rules que carrega arquivos .css. Normalmente parece um test para arquivos .css usando style-loader e css-loader com um objeto de opções. O objeto de opções dentro da entrada do css-loader é onde todos os erros de esquema se originam. Abra esse objeto e compare-o com a lista de opções válidas da sua versão instalada do css-loader.
Aplique a correção correta para seu subtipo de erro
Para um erro de propriedade desconhecida: renomeie ou mova a propriedade para sua nova localização. localIdentName vira modules.localIdentName. minimize foi removida - instale o css-minimizer-webpack-plugin separadamente. camelCase foi removida - use a opção exportLocalsConvention no objeto modules em vez disso. Para um erro de tipo errado: converta modules: true em um objeto com mode: 'local' se precisar de configuração de CSS Modules, ou mantenha-o como booleano se não precisar.
Valide a config corrigida antes de recompilar
Cole o webpack.config.js atualizado no Validador de Configuração Webpack para confirmar que todos os erros de esquema foram resolvidos antes de rodar a build completa. Isso detecta qualquer erro secundário introduzido pela correção, poupando outro ciclo de build.
Validador de Configuração Webpack
Cole seu webpack.config.js e valide instantaneamente todas as opções de loaders - detecta erros de esquema do css-loader, regras de módulo inválidas e erros de configuração de saída antes da sua próxima build.
Erros comuns de configuração do css-loader
Estes são os erros de opções específicos que aparecem com mais frequência nas falhas de validação de esquema do css-loader. Cada entrada mostra o padrão de config quebrado, a substituição correta e a qual versão do css-loader a mudança se aplica.
localIdentName no nível superior (v3 → v4)
No css-loader v3, o localIdentName era uma opção de nível superior que controlava a geração de nomes de classe do CSS Modules. Na v4+, ele foi movido para dentro do objeto modules. A correção é aninhá-lo dentro de modules com a propriedade localIdentName definida com seu padrão. A mensagem de erro diz options has an unknown property 'localIdentName' - este é o erro de migração do css-loader número um.
Opção minimize removida (v4+)
A opção minimize foi removida do css-loader na v4. A minificação de CSS agora é feita separadamente pelo css-minimizer-webpack-plugin no array optimization.minimizer. Remova minimize por completo das opções do seu css-loader e adicione o css-minimizer-webpack-plugin à sua build se a minificação for necessária. O Validador de CSS pode ajudar a verificar se o CSS de saída está correto após trocar a ferramenta de minificação.
Opção camelCase removida (v6)
O css-loader v6 removeu a opção camelCase de nível superior. A substituição é modules.exportLocalsConvention, que aceita camelCase, camelCaseOnly, dashes ou dashesOnly. Atualize suas opções para definir exportLocalsConvention dentro do objeto modules. Sem essa mudança, qualquer instalação v6 com a antiga propriedade camelCase dispara um erro de propriedade desconhecida.
| Opção antiga (quebrada) | Versão do css-loader | Substituição correta |
|---|---|---|
| options.localIdentName | v4+ | options.modules.localIdentName |
| options.minimize | v4+ | plugin css-minimizer-webpack-plugin |
| options.camelCase | v6+ | options.modules.exportLocalsConvention |
| options.modules: true | v4+ (para personalizar) | options.modules: { mode: "local", ... } |
| options.importLoaders: true | todas | options.importLoaders: 1 (número, não booleano) |
| options.sourceMap: "inline" | v4+ | options.sourceMap: true (somente booleano) |
Note
Validando sua configuração do webpack
A maneira mais eficiente de resolver erros de esquema do css-loader - especialmente após uma atualização de versão maior - é validar todo o webpack.config.js de uma vez em vez de descobrir erros uma build por vez. Várias ferramentas tornam isso rápido.
O Validador de Configuração Webpack
O Validador de Configuração Webpack aceita seu webpack.config.js completo e reporta todas as violações de esquema de cada loader, plugin e opção de nível superior em uma única passagem. Ele mostra a mesma notação de caminhos que o Webpack usa nos erros de execução, então você pode cruzar a saída com o erro visto no terminal. Cole sua config, receba todos os problemas de uma vez, corrija-os e cole novamente para confirmar - sem ciclo de build necessário.
Verificar primeiro o arquivo de config por erros de sintaxe JavaScript
Se o Webpack não consegue nem parsear seu webpack.config.js por causa de um erro de sintaxe JavaScript - chaves desemparelhadas, vírgula faltante ou spread inválido - você verá um erro de parsing do Node.js em vez de um erro de validação de esquema. Use o Validador de Sintaxe JavaScript para descartar problemas de sintaxe antes de depurar a validação de esquema.
Validando arquivos de configuração relacionados
O css-loader raramente é o único arquivo de configuração em um pipeline de build. Se você usa PostCSS para transformações, o Validador de Configuração PostCSS detecta erros de ordenação de plugins e dependências faltantes no postcss.config.js. Se você usa stylelint para checagens de qualidade CSS, o Validador de Configuração Stylelint valida seu .stylelintrc antes de ele interferir na build. O Validador de Configuração ESLint é útil se sua cadeia de build também roda ESLint - más configurações ali podem se manifestar como erros de build parecidos com erros de loader.
Validador de Configuração PostCSS
Valide o postcss.config.js para erros de ordenação de plugins e de opções - detecta problemas de configuração que frequentemente acompanham erros de esquema do css-loader em setups Webpack complexos.
css-loader com PostCSS e CSS Modules
A maioria dos setups Webpack de produção usa css-loader junto com PostCSS e CSS Modules. Cada um adiciona suas próprias opções e seus próprios possíveis erros de esquema. Entender como eles interagem previne os conflitos de configuração mais comuns.
A opção importLoaders
Quando o PostCSS roda em um arquivo CSS antes do css-loader, você deve definir importLoaders: 1 (ou mais) nas opções do css-loader para garantir que as declarações @import do CSS também passem pelo PostCSS. Sem isso, os arquivos importados escapam do PostCSS. Um erro comum é definir importLoaders: true - isso dispara um erro de validação de esquema porque a opção deve ser um número, não um booleano. Defina-o com o número de loaders que rodam antes do css-loader na cadeia.
CSS Modules com nomes de classe personalizados
A personalização de nomes de classe do CSS Modules mudou para o sub-objeto modules no css-loader v4. Uma configuração completa de CSS Modules com um padrão de identidade personalizado usa mode, localIdentName e exportLocalsConvention - cada um como opção separada com suas próprias restrições de esquema. Passar qualquer um deles no nível superior de options em vez de dentro de modules produz um erro de propriedade desconhecida.
Opções url e import
As opções url e import do css-loader controlam se o loader resolve referências url() e declarações @import. Ambas aceitam um booleano ou um objeto com função de filtro. Passar uma função pura - em vez de um objeto com propriedade filter - dispara um erro de esquema porque o esquema da opção espera um objeto com propriedade filter, não uma função solta. Envolva sempre as funções de filtro no formato de objeto esperado.
Warning
Key takeaways
- Os erros de validação de esquema do css-loader disparam antes da compilação e sempre nomeiam o caminho exato da opção inválida - leia o caminho primeiro, não o stack trace.
- A causa mais comum é usar a sintaxe de opções do css-loader v3 (localIdentName plano, minimize, camelCase) com uma instalação v4+ ou v6+.
- No css-loader v4+, todas as opções do CSS Modules se movem para dentro de um sub-objeto modules - localIdentName passa a ser modules.localIdentName.
- minimize foi removida na v4 - use o css-minimizer-webpack-plugin em optimization.minimizer em vez disso.
- importLoaders deve ser um número (ex. 1), não um booleano - passar true dispara um erro de validação de tipo.
- Use o Validador de Configuração Webpack para detectar todos os erros de esquema em uma passagem antes de recompilar.
- Verifique também as configs relacionadas - más configurações de PostCSS, ESLint e Stylelint frequentemente acompanham erros do css-loader em pipelines complexos.