Static content deploy no Magento 2: estratégias e opções

O static content deploy costuma ser a etapa mais lenta de um release do Magento 2. Numa loja com alguns temas e vários locales, pode levar mais que todo o resto junto, e gera dezenas de milhares de arquivos. O Magento oferece três estratégias de deploy e um conjunto de opções para controlar o que é gerado. Escolher as certas encurta os builds e evita uma loja que carrega sem estilos em um idioma. Este guia cobre o setup:static-content:deploy no Magento Open Source e no Adobe Commerce 2.4.8.

O que o comando produz

O setup:static-content:deploy reúne CSS, JavaScript, fontes, imagens e templates de todos os módulos e temas, compila LESS em CSS nos temas baseados no Luma, aplica minificação se estiver ativa e grava o resultado em pub/static. A estrutura de pastas é:

pub/static/<area>/<Vendor>/<theme>/<locale>/...
pub/static/frontend/Magento/luma/en_US/css/styles-m.css
pub/static/adminhtml/Magento/backend/en_US/js/...

Cada combinação de área, tema e locale é uma árvore separada. Com dois temas de storefront e quatro locales, mais o admin, você faz deploy de pelo menos nove conjuntos completos de arquivos. A maioria é idêntica entre locales, que é o que as estratégias tentam resolver.

O comando também grava o pub/static/deployed_version.txt. O Magento usa esse valor como segmento de versão nas URLs estáticas, como /static/version1731240000/..., para que navegadores e CDNs busquem os arquivos novos depois de um deploy. Isso é o static file signing, controlado por dev/static/sign, e deve ficar ligado em produção.

As três estratégias

Você escolhe a estratégia com -s ou --strategy.

standard

Faz deploy de todos os arquivos de cada combinação de tema e locale separadamente. É a mais direta e a mais lenta. Cada locale recebe uma cópia completa de tudo.

quick

A padrão. Faz deploy completo de um locale por tema e, para os outros locales, copia os arquivos que não dependem do locale e processa só os que dependem. Dicionários JavaScript traduzidos e alguns templates diferem por locale, a maior parte do CSS e das imagens não. Isso reduz bastante o tempo de deploy em lojas com vários locales, e o resultado parece igual ao standard para o navegador.

compact

Em vez de copiar os arquivos compartilhados para cada pasta de locale, o compact os guarda uma vez em pastas base compartilhadas e grava arquivos de mapa para que cada tema e locale saiba onde encontrá-los. Produz bem menos arquivos e usa menos disco. O custo é que as URLs dos arquivos compartilhados apontam para os locais base, e algumas configurações, principalmente extensões de terceiros que montam URLs estáticas na mão, assumem a estrutura de pastas do standard. Teste com cuidado o storefront e o admin se escolher essa.

bin/magento setup:static-content:deploy en_US pt_BR -s quick -j 4
bin/magento setup:static-content:deploy en_US pt_BR -s compact -j 4

Para a maioria das lojas, quick é o padrão certo. Vale testar o compact quando espaço em disco, número de arquivos ou tamanho de artefato é um problema real, por exemplo com muitos locales.

Jobs em paralelo

A opção -j ou --jobs roda o trabalho de deploy de temas e locales diferentes em processos paralelos. Mais jobs ajudam até o número de núcleos de CPU. Acima disso, os processos disputam CPU e memória. Cada job precisa da própria memória, então fique de olho no memory limit do PHP CLI e na RAM do servidor ao aumentar. Num servidor de produção pequeno em que o deploy roda junto com tráfego real, mantenha o número de jobs baixo para a loja não ficar lenta.

Faça deploy só do que você usa

O arquivo mais rápido é o que você não gera. O comando tem opções para limitar o escopo.

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

bin/magento setup:static-content:deploy en_US \
  --area adminhtml \
  --theme Magento/backend \
  -j 2

Outras opções úteis:

• --exclude-theme pula temas, por exemplo Magento/luma quando nenhuma store view o usa. Não exclua um tema que é pai do tema que você usa.
• --exclude-language pula locales.
• --exclude-area pula uma área.
• Flags como --no-javascript, --no-css, --no-images, --no-fonts e --no-html pulam tipos de arquivo. Úteis para depurar um deploy lento, raramente para um release de verdade.

Listar os locales explicitamente importa. Sem o argumento de locale, o comando faz deploy só do en_US, que é um motivo comum de uma store view em outro idioma carregar sem estilos. O locale do admin importa também. Se um usuário do admin escolheu outro locale de interface, esse locale precisa dos arquivos estáticos do admin.

Rodando sem o modo production

Nos modos developer e default, o comando se recusa a rodar a menos que você adicione -f ou --force. É proposital. No modo developer os arquivos estáticos normalmente são gerados sob demanda, e um deploy completo raramente é o que você quer localmente. Num servidor de build você geralmente roda em modo production, ou passa -f de propósito.

Build sem banco de dados

Por padrão o comando lê temas e locales das stores no banco. Um runner de CI normalmente não tem banco. A solução é exportar essa configuração para o app/etc/config.php:

bin/magento app:config:dump scopes themes i18n

Com escopos, temas e configurações de locale no arquivo versionado, o static content deploy pode rodar numa máquina sem conexão com banco. Essa é a base da etapa de build no guia de deploy sem downtime e no guia de deploy em modo production.

Minificação, merge e bundling

Essas configurações mudam o que o deploy produz. Elas ficam na configuração de developer, que o admin esconde no modo production, então você as define com config:set e, idealmente, guarda no config.php:

bin/magento config:set dev/js/minify_files 1
bin/magento config:set dev/css/minify_files 1
bin/magento config:set dev/template/minify_html 1
bin/magento config:set dev/js/merge_files 0
bin/magento config:set dev/js/enable_js_bundling 0

A minificação em geral é segura e reduz o tamanho dos arquivos. Merge e o bundling nativo são outra história. O bundling nativo do Magento coloca grandes partes do conjunto de módulos do RequireJS em poucos arquivos grandes por tipo de página. Num tema Luma isso muitas vezes deixa o primeiro carregamento mais pesado, não mais leve. Com HTTP/2, muitos arquivos pequenos não são o problema que já foram. Eu mantenho merge e bundling desligados por padrão e só ligo uma abordagem de bundling avançada depois de medir. O guia de JS bundling entra nas opções.

Seja qual for a escolha, mude essas configurações antes do static content deploy, não depois. O deploy grava os arquivos de acordo com as configurações vigentes.

Hyvä e static content

Temas Hyvä não usam RequireJS nem LESS no storefront. O CSS deles é gerado com Tailwind durante a etapa de build do tema, antes do static content deploy, e o deploy então copia o resultado compilado. O comando continua rodando e continua produzindo o admin e as áreas baseadas em Luma que você mantiver, como um fallback de checkout em Luma. O total de trabalho é menor, um dos benefícios práticos descritos na comparação Hyvä vs Luma.

Solução de problemas

• Estilos faltando em uma store view: o locale dela não estava no comando de deploy, ou o tema atribuído a ela foi excluído.
• Erros de compilação LESS: o deploy para com uma mensagem apontando para um arquivo LESS. Corrija a fonte. Erros aqui muitas vezes vêm do LESS de um módulo de terceiros que depende de variáveis definidas só no Luma.
• CSS antigo depois do deploy: o static signing está desligado, ou uma CDN guardou os arquivos antigos na mesma URL. Confira o dev/static/sign e se o deployed_version.txt mudou.
• O deploy fica sem memória: diminua o -j ou aumente o memory limit da CLI, por exemplo com php -d memory_limit=4G bin/magento ....
• Arquivos aparecem em pub/static durante a execução: a loja não está em modo production, então arquivos faltando são gerados sob demanda.

Antes de um novo deploy completo, limpe a saída antiga para evitar sobras de temas removidos. Apague o conteúdo de pub/static exceto o arquivo .htaccess e limpe o var/view_preprocessed.

FAQ

Qual estratégia de static content deploy devo usar?

Quick é a padrão e a escolha certa para a maioria das lojas. Teste o compact quando o número de arquivos ou o uso de disco for um problema, e teste a loja com cuidado depois da troca.

Por que o static content deploy só gera o en_US?

Sem argumentos de locale o comando faz deploy só do en_US. Liste no comando todos os locales usados pelas suas store views e pelos usuários do admin.

Posso rodar o setup:static-content:deploy no modo developer?

Só com a flag -f ou --force. No modo developer os arquivos normalmente são gerados sob demanda, então um deploy completo costuma ser desnecessário.

Devo ativar o JS bundling do Magento?

Não por padrão. O bundling nativo muitas vezes deixa o primeiro carregamento mais pesado no Luma. Meça primeiro e considere um bundling avançado.

Atendo como freelancer em Magento e Adobe Commerce, incluindo pipelines de build e deploy. Se precisa de ajuda com isso, fale comigo.