CSS e JavaScript não carregam no Magento 2 após deploy? Faça estes 8 testes

Quando CSS e JavaScript não carregam no Magento 2, a loja pode aparecer sem formatação, exibir menus inativos ou impedir o funcionamento do checkout. O problema é comum após deploy, troca de tema, atualização de módulo, mudança de domínio ou alteração na infraestrutura.

Antes de limpar todos os caches ou apagar diretórios, identifique quais arquivos falharam e em qual camada a resposta foi interrompida. Os oito testes abaixo ajudam a separar falhas de geração, publicação, permissão, URL, servidor web e CDN.

Por que CSS e JavaScript não carregam no Magento 2?

O Magento utiliza arquivos estáticos de módulos, bibliotecas e temas para montar o frontend e o painel administrativo. Dependendo do modo de operação e da configuração, esses arquivos podem ser publicados em pub/static, agrupados, minificados, assinados com uma versão e entregues por servidor web, proxy ou CDN.

Uma página sem estilo não significa necessariamente que os arquivos estejam ausentes. O navegador também pode rejeitá-los por redirecionamento, tipo de conteúdo incorreto, bloqueio de segurança, certificado inválido ou resposta HTML no lugar do CSS ou JavaScript esperado.

1. Descubra exatamente qual recurso está falhando

Abra as ferramentas de desenvolvedor do navegador e consulte as abas Network e Console. Recarregue a página sem preservar uma resposta antiga e filtre as requisições por CSS e JavaScript.

Registre pelo menos:

• URL completa do arquivo;
• status HTTP retornado;
• tipo de conteúdo da resposta;
• domínio responsável pela entrega;
• mensagem exibida no console;
• diferença entre frontend, checkout e painel.

Um erro 404 aponta para um caminho inexistente ou uma regra de servidor inadequada. Já um 403 sugere bloqueio ou permissão. Um 500 exige consulta aos logs. Se a requisição retorna status 200, mas o conteúdo é uma página HTML, pode existir redirecionamento, página de erro personalizada ou fallback incorreto.

2. Confirme o modo de operação e o estado da aplicação

No diretório raiz do projeto, execute os comandos com o mesmo usuário utilizado na manutenção da aplicação:

php bin/magento deploy:mode:show
php bin/magento maintenance:status
php bin/magento cache:status

Em modo de produção, alterações em temas e módulos normalmente precisam entrar em um processo de deploy que inclua a publicação dos arquivos estáticos. Em desenvolvimento, o comportamento pode ser diferente, especialmente quando a infraestrutura permite a geração ou resolução dinâmica dos recursos.

Não altere o modo da loja apenas para tentar corrigir o sintoma. Essa mudança pode executar operações adicionais e aumentar o tempo de indisponibilidade. Primeiro confirme se o pipeline utilizado corresponde ao modo efetivamente configurado.

3. Verifique se o conteúdo estático foi publicado

Examine se os arquivos solicitados pelo navegador existem em pub/static. Considere a área, o tema, o idioma e o caminho exibido na própria requisição. Uma loja com mais de um locale pode ter recursos publicados para um idioma e ausentes em outro.

Em homologação, reproduza o processo de publicação usado pela equipe. Um exemplo básico é:

php bin/magento setup:static-content:deploy pt_BR -f

O idioma deve refletir os locales realmente utilizados pela instalação. Também é importante conferir a saída completa do comando: mensagens de sucesso parciais podem esconder falhas em um tema ou módulo específico.

Evite executar uma publicação pesada diretamente em horário de pico sem avaliar consumo de CPU, memória e disco. O procedimento mais previsível é gerar os artefatos no pipeline ou em uma etapa controlada do deploy.

4. Compare código, dependências e arquivos publicados

Um nó pode receber o novo código enquanto outro continua entregando arquivos da versão anterior. Isso produz falhas intermitentes: a página referencia um identificador novo, mas parte da infraestrutura ainda possui o conteúdo antigo.

Confirme se todos os servidores utilizam o mesmo commit, o mesmo composer.lock e o mesmo conjunto de artefatos. Se o deploy parou durante a instalação de pacotes, investigue o conflito antes de repetir atualizações. Veja também como tratar um erro do Composer no Magento 2 sem quebrar a loja.

Em ambientes com armazenamento compartilhado, valide se a montagem está disponível em todos os nós. Em ambientes com artefatos locais, confira se cada servidor recebeu exatamente o mesmo pacote.

5. Revise proprietário, permissões e acesso do servidor web

O usuário do PHP ou do servidor web precisa conseguir acessar os diretórios necessários. Entretanto, permissões excessivamente abertas não são uma correção aceitável. Usar permissões globais de escrita pode expor a aplicação e ainda mascarar o proprietário incorreto.

Comece apenas inspecionando o caminho problemático:

ls -la pub/static
namei -l pub/static/frontend

Compare proprietário e grupo com o padrão definido pela infraestrutura. Verifique também se o processo de deploy cria arquivos com um usuário diferente daquele utilizado pelo servidor web. A correção deve seguir a política de permissões do ambiente, sem aplicar recursivamente valores genéricos em toda a instalação.

6. Confira URLs base, HTTPS, domínio e CDN

Se o HTML aponta para um domínio antigo, protocolo HTTP ou hostname interno, revise as configurações de URL estática e mídia nos escopos correto. Faça primeiro uma leitura:

php bin/magento config:show web/unsecure/base_static_url
php bin/magento config:show web/secure/base_static_url
php bin/magento config:show web/secure/use_in_frontend

Valores vazios para as URLs estáticas podem ser normais quando o Magento deve herdar a URL base. O problema aparece quando existe um valor explícito incorreto em algum website ou store view, ou quando variáveis de ambiente substituem a configuração esperada.

Se houver CDN, teste a URL de origem e a URL distribuída. Uma resposta antiga na borda, uma regra de cache inadequada ou um certificado incompatível pode afetar apenas determinados clientes. O Varnish também deve ser analisado separadamente: confira este roteiro quando o Varnish no Magento 2 retorna apenas MISS.

7. Teste versionamento, minificação e bundling

O Magento pode adicionar uma assinatura ao caminho dos arquivos estáticos para evitar que navegadores reutilizem versões antigas. Se o HTML contém uma versão, mas o servidor remove ou interpreta incorretamente esse trecho da URL, os recursos podem retornar 404.

Verifique a URL que falhou e as regras do Nginx ou Apache. Não remova o versionamento permanentemente apenas para fazer a página voltar. Ele é importante para manter coerência entre o HTML e os recursos após um deploy.

Minificação, união e bundling também podem revelar incompatibilidades entre módulos. Se um arquivo combinado falha, reproduza o cenário em homologação e compare o comportamento com essas otimizações desativadas temporariamente. A mudança serve como diagnóstico, não como substituta da correção no código.

8. Limpe somente a camada relacionada ao problema

Depois de corrigir arquivos, configurações ou regras do servidor, invalide apenas as camadas necessárias. Limpar tudo antes do diagnóstico pode remover evidências e aumentar a carga da loja.

Consulte o estado dos caches e limpe os tipos relacionados à alteração:

php bin/magento cache:status
php bin/magento cache:clean config layout block_html full_page

Nem todos esses tipos precisam ser limpos em qualquer ocorrência. Uma mudança de configuração pode exigir config; uma atualização de layout pode envolver layout e block_html. A publicação de arquivos ausentes, por sua vez, não será resolvida apenas com limpeza de cache.

Também não reindexe todo o catálogo para corrigir CSS. Indexadores tratam dados como preços, categorias e busca, não a publicação do frontend. Se existirem sintomas de catálogo em paralelo, use um diagnóstico específico para indexadores Magento 2 travados.

Como validar a correção sem criar outro problema

Após ajustar a causa, teste uma janela anônima e diferentes páginas: inicial, categoria, produto, carrinho, checkout e painel. Confirme que os recursos retornam status adequado, tipo de conteúdo correto e ausência de erros relevantes no console.

Em uma infraestrutura com múltiplos nós ou CDN, repita as requisições e compare os cabeçalhos. Monitore os logs durante a validação para identificar 404, 403 e exceções que continuem acontecendo.

Se CSS e JavaScript não carregam no Magento 2 mesmo após esses testes, preserve URLs, horários, logs e informações do deploy. Esse conjunto reduz tentativas aleatórias e permite que uma equipe especializada investigue tema, módulos e infraestrutura com mais precisão. Para um diagnóstico técnico da sua loja, entre em contato com o Suporte Magento.

Perguntas frequentes

Por que o Magento 2 fica sem formatação depois de um deploy?

As causas mais comuns incluem conteúdo estático não publicado, artefatos diferentes entre servidores, permissões inadequadas, URL base incorreta ou cache entregando referências de outra versão. A aba Network do navegador mostra quais arquivos falharam.

Limpar o cache corrige CSS e JavaScript ausentes?

Somente quando a falha está relacionada a referências ou configurações armazenadas. Se o arquivo não foi publicado, está bloqueado ou existe apenas em parte dos servidores, limpar cache não resolve a origem.

Posso apagar todo o diretório pub/static?

Não faça isso diretamente em produção sem compreender o pipeline e os arquivos preservados pela instalação. A remoção indiscriminada pode ampliar a indisponibilidade. Reproduza o procedimento em homologação e publique novamente os artefatos de forma controlada.

É necessário reindexar o Magento após alterar o tema?

Normalmente, não. Reindexação trata estruturas de dados do catálogo, estoque, preços e busca. Alterações de tema costumam exigir compilação ou publicação de conteúdo estático e limpeza seletiva de cache, conforme o tipo de mudança.