setup:static-content:deploy lento: corte com -j, tema e locale

A conta que o comando faz

Cada pacote de arquivo estático é uma combinação de três coisas: área (frontend e adminhtml), tema e idioma. Uma loja com Luma, Blank, o tema do cliente e três idiomas instalados já pede uma dezena de pacotes, cada um com CSS, JS, fonte, imagem e dicionário de tradução.

E é sequencial. A opção que liga processo paralelo é -j, descrita no core como Enable parallel processing using the specified number of jobs, e o padrão dela é 0. Zero, não um núcleo por CPU. Enquanto você não passar -j, o servidor de 16 núcleos usa um.

Confira o que está instalado antes de sair chutando. Em Content > Design > Configuration você vê, linha por linha, qual tema cada store view usa de verdade — e normalmente é sempre o mesmo.

Os dois comandos que eu rodo

Em vez de um comando genérico, dois específicos. Primeiro a loja:

php bin/magento setup:static-content:deploy -j 4 \
  --area frontend \
  --theme Vendor/meutema \
  pt_BR

Depois o admin, que é outra área e quase sempre outro conjunto de idiomas:

php bin/magento setup:static-content:deploy -j 4 \
  --area adminhtml \
  pt_BR en_US

Repare que o idioma vai como argumento solto no fim, não como opção. As duas formas existem (-l pt_BR também funciona), mas o argumento é o que você vê na documentação da Adobe.

No admin eu deixo en_US junto de propósito: extensão de terceiro costuma trazer texto só em inglês, e o painel quebra de um jeito silencioso quando falta o pacote. Na loja, não — lá só entra o idioma que o cliente vê.

Se o comando responder NOTE: Manual static content deployment is not required in "default" and "developer" modes, a loja não está em produção. Em developer o Magento gera arquivo sob demanda e você não precisa desse comando; se quiser forçar mesmo assim, é o -f.

Tem também o --exclude-theme, útil quando você não sabe o nome exato do seu tema mas sabe que Luma não é usado. Eu prefiro a lista positiva com --theme: é mais difícil errar.

Quantos jobs, e o que costuma travar

Eu começo com -j 4 e subo até uns dois terços dos núcleos disponíveis. Cada job é um processo PHP inteiro, com o memory_limit dele: oito jobs numa máquina de 4 GB não aceleram nada, engasgam.

Três coisas fazem o paralelismo simplesmente não acontecer:

• Sem pcntl. O core só forka se pcntl_fork existir e o número de jobs for maior que 1. Muita hospedagem compartilhada corta essa extensão ou põe a função no disable_functions. Aí o -j 8 passa batido e roda em fila do mesmo jeito.
• Tempo por job. O limite padrão é 900 segundos (--max-execution-time). Catálogo com muita imagem de tema pode estourar isso e derrubar o deploy no meio.
• Bug de porta no banco. Em 2.4.7 sem patch, rodar com --jobs e ter a porta do MySQL escrita no env.php quebra com Port must be configured within host parameter. A Adobe corrige isso no patch ACSD-61366, do Quality Patches Tool.

Uma última: rode isso como o dono dos arquivos, nunca como root. Deploy feito de root deixa pub/static com dono errado e a próxima requisição do php-fpm não consegue escrever nada. Se você quer entender onde o estático entra na fila do deploy, eu detalho o resto do processo no guia de performance.