Admin do Magento em branco depois do deploy: apague o generated

Branco não é a mesma coisa que sem estilo

Antes de apagar qualquer pasta, olhe o código-fonte da página com Ctrl+U:

• Vazio ou quase vazio — erro fatal do PHP. É o caso deste texto.
• HTML inteiro, sem cor e sem layout — o CSS e o JS estão dando 404. Aí o problema é estático faltando, não classe gerada.

Confirmado que é fatal, vá atrás do erro em vez de adivinhar:

tail -50 var/log/exception.log
ls -t var/report/ | head -5

O var/report/ guarda um arquivo por exceção não tratada, com nome em hash. Abra o mais recente e você tem a classe, o arquivo e a linha. Se as duas pastas estiverem vazias, o fatal aconteceu antes do Magento carregar o logger — normalmente falta de memória ou erro de sintaxe. Nesse caso o log é o do PHP mesmo:

tail -50 /var/log/php8.4-fpm.log

E se você precisa ver o erro na tela pra não ficar no escuro, o Magento tem isso pronto:

cp pub/errors/local.xml.sample pub/errors/local.xml

O arquivo vem com <action>print</action>, que imprime o relatório em vez de mostrar a página genérica de erro. Apague o arquivo depois — em produção ele expõe caminho de servidor pra qualquer visitante.

A sequência que resolve

Com o erro apontando pra alguma coisa em generated/ — interceptor, factory, proxy —, é essa a ordem:

php bin/magento deploy:mode:show
php bin/magento maintenance:enable
rm -rf generated/code generated/metadata
php bin/magento setup:di:compile
php bin/magento cache:flush
php bin/magento maintenance:disable
sudo systemctl reload php8.4-fpm

Três observações sobre esse bloco.

O deploy:mode:show vem primeiro porque muda tudo. Em developer, o Magento gera as classes que faltam durante o request, então apagar a pasta é inofensivo e você nem precisa compilar. Em production, nada é gerado em tempo de execução: se você apagar e não rodar o setup:di:compile, a loja inteira cai, não só o admin.

A manutenção existe porque entre o rm e o fim da compilação a loja fica sem as classes. São alguns minutos de 503 controlado em vez de erro aleatório pro cliente.

O reload do PHP-FPM é pelo OPcache. Ele guarda o bytecode dos arquivos antigos e continua servindo a versão anterior das classes geradas mesmo depois de você recompilar, o que faz o erro "voltar sozinho" e você achar que o comando não funcionou.

Se o setup:di:compile morrer no meio sem mensagem clara, confira a memória. A Adobe recomenda memory_limit de 1G pra compilar código e gerar estáticos, e o valor que vale é o do PHP de linha de comando, não o do FPM.

Por que isso quebra logo depois do deploy

Três causas dão conta de quase todos os casos que eu vejo.

A pasta veio junto no pacote. Alguém empacotou o projeto com o generated/ de outra branch dentro. As classes ali dentro referenciam plugins e preferences que não existem mais no código novo, e o autoloader estoura. Coloque generated/ no .gitignore e fora do artefato de deploy.

Compilou com módulo desativado. Se o setup:di:compile rodou num ambiente com um módulo desligado e a produção está com ele ligado, os interceptors daquele módulo não foram gerados. O sintoma clássico é o admin cair só ao abrir a tela do módulo em questão. Compare com php bin/magento module:status nos dois lados.

Dono errado nos arquivos. Um sudo num comando de deploy e a pasta nova sai pertencendo ao root. O PHP-FPM não lê, o autoloader não acha e você tem exatamente o mesmo sintoma. Se depois da sequência acima ainda estiver branco, olhe ls -la generated/ antes de continuar procurando bug no código.

Uma última: apagar generated/ nunca resolve problema de dado. Se o erro fala de tabela, coluna ou de módulo com schema pendente, o caminho é setup:db:status e setup:upgrade, não recompilação.