Migração de Magento 1 para Magento 2 / Adobe Commerce: guia técnico completo preservando SEO

Fim de vida do Magento 1: o relógio parou em 30/06/2020

O suporte ao Magento 1 (tanto Magento Commerce 1 quanto Magento Open Source 1) terminou oficialmente em 30 de junho de 2020. A Adobe anunciou o fim de vida ainda em setembro de 2018 — cerca de 18 meses de antecedência — exatamente para dar tempo de re-plataforma aos lojistas. Desde a data de EOL, a Adobe não publica mais patches de segurança, correções de qualidade nem oferece suporte técnico para o Magento 1.

Na prática, cada vulnerabilidade descoberta após junho de 2020 permanece aberta para sempre na sua loja. Não é um risco teórico. A pesquisa da Sansec sobre a campanha Cardbleed mostrou o que acontece quando milhares de lojas ficam sem patches:

Segundo a Sansec, a campanha automatizada Cardbleed infectou 2.806 lojas Magento 1 (cerca de 3% da base instalada) em poucos dias — começando com 10 lojas na sexta, saltando para 1.058 no sábado, 603 no domingo e 233 na segunda. À época, aproximadamente 95 mil lojas Magento 1 ainda operavam. A própria empresa descreve este episódio, em suas palavras, como "by far the largest one that Sansec has identified since it started monitoring in 2015".

Fonte: Sansec

O problema de conformidade PCI DSS

Além do risco direto de roubo de dados de cartão, rodar Magento 1 cria um problema de conformidade PCI DSS. A política oficial de ciclo de vida da Adobe Commerce não usa uma frase genérica para qualquer software fora de suporte — ela vincula a perda de garantia de conformidade a combinações específicas de release com versões de PHP em fim de vida (por exemplo, lojas em 2.4.6 que continuam em PHP 8.1, ou nas versões 2.4.4 e 2.4.5, presas a PHP que já chegou ao fim de vida). O raciocínio, porém, se aplica com força total ao M1: uma loja sem patches desde 30/06/2020, rodando sobre PHP igualmente morto, não tem como sustentar conformidade PCI, o que pode resultar em:

• Multas: aplicadas pelas bandeiras e pelo adquirente.
• Perda da capacidade de processar cartões: o adquirente pode suspender o merchant account.
• Responsabilidade ampliada: em caso de vazamento, o lojista responde por não manter o ambiente conforme.

De acordo com a política de ciclo de vida da Adobe, para configurações fora de suporte — como uma release atrelada a uma versão de PHP que chegou ao fim de vida — a conformidade PCI não pode ser garantida. A documentação afirma, por exemplo, que "PCI compliance cannot be guaranteed for merchants running version 2.4.6 who continue to use PHP 8.1".

Fonte: Adobe Experience League

Minha recomendação é direta: se você ainda processa cartões em Magento 1, trate a migração como prioridade máxima, não como projeto de "quando der". E, já que vai mexer na fundação, vale acoplar ao projeto um trabalho sério de segurança e hardening do Magento 2 desde o primeiro dia da nova loja.

Por que migrar: o custo honesto de ficar vs. o custo de migrar

Segurança é o motivo número um, mas um especialista não vende migração com frases de blog ("APIs robustas", "plataforma moderna"). A decisão é financeira e tem dois lados. Vou ser honesto: migrar custa caro e leva meses. A pergunta certa não é "vale a pena migrar?", e sim "o custo de não migrar já superou o custo de migrar?". Para a esmagadora maioria das lojas M1 em 2026, a resposta é sim.

O custo de NÃO migrar

• Risco PCI e multa: sem garantia de conformidade, você fica exposto a multas do adquirente e à suspensão do merchant account — perda direta de receita.
• Perda de vendas em incidente: um skimmer de cartão (Magecart) não só vaza dados; quando descoberto, derruba a conversão e a reputação. Limpeza emergencial e perícia custam mais do que o projeto de migração.
• Travamento tecnológico: gateways modernos, antifraude, ERPs e marketplaces vão deixando de publicar conectores M1. Você fica impossibilitado de aceitar integrações e extensões novas — o negócio para de evoluir.
• Performance impossível: o M1 não tem full page cache nativo, indexadores assíncronos nem GraphQL. Não há como atingir Core Web Vitals competitivos.

O custo de migrar (estimativa honesta)

Não existe número de tabela aqui — o orçamento depende do tamanho do catálogo, da quantidade de extensões/integrações e da escolha de tema. Como regra geral de mercado, projetos sérios de re-plataforma M1→M2 se medem em meses (raramente menos de 3, frequentemente 6+), divididos em quatro frentes que detalho na seção de re-plataforma. Os principais drivers de custo são, em ordem: (1) reconstrução de integrações/ERP/NF-e, (2) re-desenvolvimento de frontend, (3) re-implementação de extensões e (4) a migração de dados em si — que, paradoxalmente, costuma ser a frente mais barata.

O ganho mensurável: a stack moderna do 2.4.8

A versão atual, Adobe Commerce / Magento Open Source 2.4.8, exige uma stack completamente diferente da do M1. É essa base que destrava performance e GraphQL:

Vale destacar uma mudança recente que pega muita gente de surpresa: nas versões mais novas o Valkey (fork open source do Redis, criado após a mudança de licença do Redis) passou a ser o backend de cache e sessão de referência, ao lado do Redis. Em campo, a combinação que entrega o salto real de performance é full page cache nativo + Varnish 7.6 na frente + tema Hyvä: é com esse trio que vejo lojas saírem de um TTFB de segundos no Luma/M1 para faixas de centenas de milissegundos e passarem em LCP < 2,5 s em mobile — algo que o M1 simplesmente não alcança. O GraphQL, por sua vez, é o que viabiliza storefronts headless (PWA, Vue Storefront/Alokai, Hyvä React) e integrações desacopladas — destravando frentes de negócio como app nativo e omnichannel.

Janela de suporte previsível

Diferente do M1, o ciclo de vida do Adobe Commerce oferece uma janela de três anos de suporte (patches de qualidade e segurança) a partir do General Availability, com um ano adicional de extended support, sem custo, para a versão 2.4.6. A Adobe não fornece correções para dependências de terceiros (PHP, MySQL etc.) que cheguem ao fim de vida dentro dessa janela — manter a stack atualizada continua sendo responsabilidade do lojista.

Conforme a documentação de system requirements da Adobe, o Adobe Commerce / Magento Open Source 2.4.8 exige PHP 8.3 ou 8.4, adota o OpenSearch 2.19 como motor de busca preferido (com Elasticsearch 8.17 ainda suportado on-premises), roda sobre MySQL 8.4 / MariaDB 11.4, usa Composer 2.9.3+, RabbitMQ 4.1 e tem o Valkey 8 como solução de cache de referência.

Fonte: Adobe Experience League

Magento 2 não é um "upgrade": é re-plataforma

Este é o ponto que mais gera frustração em projetos mal planejados. A arquitetura do Magento 2 é completamente diferente da do Magento 1. Não existe um botão de "atualizar". Você instala uma loja Magento 2 nova e transfere os dados do banco; tudo o que é código, extensão e tema precisa ser refeito.

A documentação oficial de planejamento (create-plan) é explícita ao instruir que o primeiro passo é revisar as extensões do site atual e migrar o código das extensões do Magento 1 para o Magento 2, adaptando o código para compatibilidade com M2 e fazendo o mapeamento de estruturas de dados customizadas.

O que precisa ser reconstruído

• Código customizado: módulos próprios do M1 não rodam no M2; precisam ser portados para a nova arquitetura (DI, áreas, namespaces, layout XML do M2).
• Extensões de terceiros: não há compatibilidade. É preciso encontrar o equivalente M2 no Marketplace ou reconstruir a funcionalidade.
• Tema e storefront: o Data Migration Tool NÃO migra tema, design nem storefront. O frontend é construído do zero (Luma, Hyvä, PWA ou custom).
• Integrações: conectores de ERP, gateways, marketplaces e emissão fiscal precisam ser reimplementados sobre as APIs do M2.

As quatro frentes de orçamento

Na minha experiência, lojistas que tratam a migração como "copiar dados e está pronto" descobrem, no meio do caminho, que precisam de um projeto de desenvolvimento frontend completo e de re-implementação de cada integração. Por isso eu sempre separo o orçamento em quatro frentes distintas:

1. Migração de dados (Data Migration Tool — catálogo, clientes, pedidos, configs). Costuma ser a frente mais barata.
2. Re-desenvolvimento de tema e frontend (reconstrução completa).
3. Re-implementação de extensões (equivalentes M2 ou código novo).
4. Re-implementação de integrações — pagamento, antifraude e, no Brasil, a integração com ERP e emissão de NF-e, que praticamente nunca tem equivalente M1 reaproveitável e costuma ser a frente mais cara.

Encarar a migração como re-plataforma desde o primeiro dia evita estouro de prazo e orçamento. É mais honesto chamar o projeto de "construção de uma nova loja que herda os dados da antiga" do que de "upgrade".

Data Migration Tool: settings, data, e o delta em loop até o cutover

O Data Migration Tool é a ferramenta oficial da Adobe que transfere os dados do banco do Magento 1 para o Magento 2. Regra de ouro: use sempre a mesma versão liberada do Magento 2 e do Data Migration Tool (para Magento 2.x.y, use Data Migration Tool 2.x.y). Casar versões evita 90% dos erros bobos de integridade. A instalação é via Composer:

composer require magento/data-migration-tool:<version>

A ferramenta opera em três modos, que a Adobe recomenda fortemente executar nesta ordem: settings → data → delta (changes). O argumento de caminho do config.xml é obrigatório em todos eles:

O gotcha número 1: o delta só captura o que mudou DEPOIS do primeiro migrate:data

Este é o detalhe que separa quem leu a doc de quem já operou a ferramenta. O delta não é mágica retroativa. Quando o migrate:data roda pela primeira vez e passa no integrity check, a ferramenta instala tabelas de changelog (prefixo m2_cl_*) e os triggers correspondentes no banco do Magento 1. A partir daí — e só a partir daí — esses triggers passam a registrar cada inserção/atualização/exclusão. Tudo que mudou no M1 antes desse momento já entrou no migrate:data; tudo que mudar depois é capturado pelo delta. Se você esquecer de rodar o data e tentar o delta direto, não há nada para capturar — os triggers nem existem.

Segundo a documentação da Adobe, durante a migração de dados o Data Migration Tool instala tabelas de changelog (com prefixo m2_cl_*) e triggers correspondentes no banco do Magento 1, essenciais para garantir que você migre apenas as mudanças feitas desde a última migração de dados. As mudanças rastreadas incluem o que clientes adicionam pelo storefront (pedidos, avaliações, alterações de perfil) e as operações com pedidos, produtos e categorias no Admin.

Fonte: Adobe Experience League

O delta roda em LOOP até o cutover — não é cron

Outro mal-entendido comum: o delta não é um job que você dispara uma vez e esquece, nem é algo que o cron do M2 faz por você (lembre que os cron jobs do M2 ficam desligados durante a migração). O migrate:delta é um processo contínuo: ele migra o que mudou, dorme alguns segundos e roda de novo, indefinidamente, até você abortar com CTRL-C — o que você só faz no instante do cutover.

Conforme a documentação da Adobe, a migração incremental é um processo contínuo que reinicia automaticamente a cada 5 segundos ("Incremental migration is a continuous process; it automatically restarts every 5 seconds"), podendo ser interrompido com CTRL-C.

Fonte: Adobe Experience League

Na prática, eu deixo o delta rodando dentro de um screen ou tmux nos dias que antecedem o cutover, para sobreviver a quedas de SSH. Se eu precisar de controle mais fino (logar cada ciclo, rodar a cada N minutos via cron temporário em vez do loop nativo), um wrapper resolve:

# Loop manual: roda o delta a cada 60s e registra em arquivo
while true; do
  php -d memory_limit=4G bin/magento migrate:delta /caminho/config.xml \
    >> var/log/delta_run.log 2>&1
  sleep 60
done

As flags -r e -a: cuidado com o --auto em produção

bin/magento migrate:<mode> [-r|--reset] [-a|--auto] {<path to config.xml>}

• -r | --reset: reinicia a migração do começo, descartando o progresso salvo. Use à vontade em dry run para repetir o ensaio.
• -a | --auto: impede a migração de parar quando encontra erros de integrity check. NUNCA use em produção. O --auto mascara incompatibilidades de estrutura e segue em frente, podendo corromper a migração silenciosamente. Eu só uso -a em dry run, e ainda assim para diagnosticar a lista completa de erros de uma vez — depois resolvo cada um no map.xml e rodo sem a flag.

Os três estágios internos e como ler o log

Dentro de cada step, a ferramenta executa três estágios, sempre nesta ordem:

1. Integrity Check: compara nomes e tipos de campos das tabelas para verificar compatibilidade entre as estruturas M1 e M2. É aqui que aparecem os erros que você resolve no mapeamento.
2. Data Transfer: transfere os dados tabela por tabela.
3. Volume Check: compara a quantidade de registros entre as tabelas para confirmar que a transferência foi bem-sucedida.

Os erros e o andamento vão para o migration.log (por padrão em var/migration.log). Os dois erros que mais vejo: Source documents are not mapped (tabela existe no M1 mas não foi mapeada para o M2 → resolve com <ignore> ou regra no map.xml) e Mismatch of entities in the document no Volume Check (contagens divergem → quase sempre porque alguém criou entidade no M2, ou porque o delta ainda não rodou).

Tempo realista e dimensionamento

Catálogos grandes levam horas. Não existe número universal, mas a regra de campo é: o migrate:data de uma loja com algumas centenas de milhares de produtos e milhões de pedidos roda em horas, não minutos, e o gargalo costuma ser pedidos/EAV, não produtos. Por isso o dry run não serve só para validar — serve para cronometrar. Eu anoto o tempo de cada step no ensaio e uso esse número para dimensionar a janela de cutover. Para não tomar timeout/out-of-memory, o processo CLI precisa de folga:

# memory_limit alto e sem teto de tempo para o processo de migração
php -d memory_limit=4G -d max_execution_time=0 \
  bin/magento migrate:data /caminho/config.xml

Se o Volume Check falhar por timeout em catálogos enormes, ou o integrity demorar demais, vale rodar por partes (mapear/ignorar grupos de documentos) e garantir max_execution_time=0 no CLI. A ferramenta salva o progresso conforme executa, então uma interrupção não obriga a recomeçar a migração de horas.

config.xml, map.xml e crypt_key: resolvendo erros de integridade na prática

Antes de rodar qualquer comando, é preciso configurar a ferramenta. O arquivo primário é o config.xml.dist: ele especifica as conexões de banco do M1 e do M2, a crypt_key, a configuração de steps e os links para os arquivos de mapeamento. O map.xml.dist é o arquivo de mapeamento exigido pelo map step.

Localização por edição

Os arquivos ficam dentro de vendor/magento/data-migration-tool/etc/, em subdiretórios que dependem da edição de origem e destino:

Cada um desses diretórios ainda tem subpastas por versão (por exemplo, 1.9.4.5-to-2.4.x), refletindo o par exato de versões de origem e destino. Confira sempre que o diretório usado bate com as versões reais do seu M1 e do seu M2.

O config.xml mínimo (com crypt_key)

Copie o arquivo de distribuição e edite com seus dados. Recomendo versionar suas customizações em um módulo próprio (app/code/Vendor/Migration/etc/<edition>/<version>/config.xml) para manter o mapeamento no Git:

cp config.xml.dist config.xml

<config>
  <source>
    <database host="127.0.0.1" name="magento1_db" user="m1user" password="***"/>
  </source>
  <destination>
    <database host="127.0.0.1" name="magento2_db" user="m2user" password="***"/>
  </destination>
  <options>
    <crypt_key>COLE_AQUI_A_CHAVE_DO_M1</crypt_key>
    <!-- map adicional para extensões, ver abaixo -->
    <map_file>etc/opensource-to-opensource/1.9.4.5-to-2.4.x/map.xml</map_file>
  </options>
</config>

crypt_key: o erro que quebra o login de TODA a base

Este é, de longe, o gotcha mais grave da configuração. A <crypt_key> deve receber exatamente a chave de criptografia do Magento 1, que fica no app/etc/local.xml do M1, dentro da tag <crypt><key>...</key></crypt>. Se você informar a chave errada (ou esquecer), os dados criptografados não são descriptografados corretamente: senhas de clientes, dados de pagamento salvos e outros campos sensíveis quebram silenciosamente — e você só descobre quando a base inteira não consegue fazer login no go-live. Trate a crypt_key como item de checklist obrigatório do dry run: teste login de um cliente real no ambiente migrado antes do cutover.

Exemplo real de map.xml resolvendo um integrity check

Quando o log acusa Source documents are not mapped: some_table, a correção é declarada no map.xml. A estrutura tem <source> e <destination>, cada um com blocos para ignorar tabelas/campos, renomear e mover. Exemplo cobrindo os casos mais comuns:

<map xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <source>
    <document_rules>
      <!-- ignora uma TABELA inteira que não existe no M2 -->
      <ignore>
        <document>log_visitor</document>
      </ignore>
      <!-- renomeia uma tabela que mudou de nome -->
      <rename>
        <document>enterprise_logging_event</document>
        <to>magento_logging_event</to>
      </rename>
    </document_rules>
    <field_rules>
      <!-- ignora apenas um CAMPO de uma tabela -->
      <ignore>
        <field>catalog_product_entity.legacy_field</field>
      </ignore>
      <!-- renomeia um campo -->
      <move>
        <field>sales_flat_order.old_column</field>
        <to>sales_order.new_column</to>
      </move>
      <!-- transforma valor com um handler -->
      <transform>
        <field>customer_entity.gender</field>
        <handler class="Migration\Handler\SetValue">
          <param name="value" value="0"/>
        </handler>
      </transform>
    </field_rules>
  </source>
</map>

Ignorar tabela inteira vs. ignorar campo: use <ignore><document> quando a tabela do M1 não tem destino no M2 (tipicamente tabelas de log, sessão ou de módulos descontinuados) — ela é descartada por completo. Use <ignore><field> quando a tabela migra, mas um campo específico não existe no destino (ou você não quer trazê-lo). Ignorar a tabela toda quando só um campo diverge é o erro que faz você perder dados sem perceber.

class-map.xml e extensões

Para classes serializadas no banco (atributos de modelo, configs que guardam nomes de classe), há o class-map.xml, que remapeia classes do M1 para as do M2 — essencial quando você tem extensões que persistiam nomes de classe. Mapas adicionais (seus, de extensões) entram via <map_file> no config.xml, como no exemplo acima. Para extensões que criaram tabelas próprias no M1, o trabalho é mais profundo e envolve a classe de delta — detalho na seção de extensões.

Conforme a documentação da Adobe, o config.xml.dist é o arquivo principal que define as configurações de banco do Magento 1 e do Magento 2, a configuração de steps e os links para os arquivos de mapeamento; já o map.xml.dist é o arquivo de mapeamento exigido pelo map step.

Fonte: Adobe Experience League

O que migra, o que exige revalidação e a cópia correta de mídia

Entender exatamente o que a ferramenta cobre — e o que ela não cobre — é o que separa uma migração tranquila de uma cheia de surpresas no go-live. O modo data migra em massa os dados de catálogo, clientes, pedidos e configurações de loja. Avaliações e demais entidades de banco também são transferidas pela ferramenta.

Cópia de mídia: NÃO copie o cache, conserte o ownership

Os arquivos de mídia não são migrados pela ferramenta — precisam ser copiados manualmente. Mas o one-liner ingênuo de rsync esconde dois problemas reais. Primeiro: não copie os diretórios de cache de imagem (catalog/product/cache e catalog/category/cache). Eles são regenerados pelo M2 e podem facilmente dobrar o volume e o tempo da transferência à toa. Segundo: depois do rsync, os arquivos chegam com o owner errado, e o M2 não consegue escrever/regenerar mídia. O fluxo correto:

# 1) copia mídia EXCLUINDO os caches que serão regenerados
rsync -avz \
  --exclude='catalog/product/cache' \
  --exclude='catalog/category/cache' \
  magento1-root/media/ magento2-root/pub/media/

# 2) corrige ownership e permissões para o usuário do webserver
chown -R www-data:www-data magento2-root/pub/media
find magento2-root/pub/media -type d -exec chmod 0755 {} \;
find magento2-root/pub/media -type f -exec chmod 0644 {} \;

Se a sua mídia estiver em S3/CDN (cada vez mais comum), esqueça o rsync local: a abordagem é sincronizar bucket-a-bucket (ex.: aws s3 sync) ou apontar o M2 para o mesmo bucket/remote storage, e validar as URLs absolutas das imagens. Em catálogos grandes, a transferência de mídia pode levar horas — planeje banda e janela.

De acordo com a documentação da Adobe, os arquivos de mídia precisam ser copiados manualmente — em suas palavras, "Copy these files manually from the magento1-root/media directory to magento2-root/pub/media" — pois não são transferidos pela ferramenta.

Fonte: Adobe Experience League

Migra, mas EXIGE revalidação manual

• Hashes de senha de cliente: migram, mas dependem da crypt_key correta e podem precisar de upgrade de algoritmo (detalho na próxima seção). Teste login real no dry run.
• URL rewrites: revalide e alinhe o url_suffix (ver seção de SEO) — se o sufixo divergir, tudo quebra.
• Credenciais de pagamento: minha recomendação de campo é não migrar credenciais de gateway e reconfigurar cada gateway do zero por segurança — você não quer chaves de produção antigas vazando por um config exportado, e muitas integrações de pagamento M1 nem têm equivalente direto.
• Cupons / regras de carrinho: migram como cart price rules, mas confira condições e validade — algumas condições usam atributos que podem ter mudado de ID.

A regra de ouro: não crie entidades novas no M2 antes de migrar

Um erro clássico: a equipe instala o M2 e começa a cadastrar produtos, categorias ou atributos "para adiantar". A documentação alerta que, se você testa a loja M2 e roda a migração ao mesmo tempo, podem aparecer avisos de Volume Check — justamente porque você criou no M2 entidades que não existem no M1. O caminho seguro é deixar a ferramenta popular o catálogo e só depois fazer ajustes e novos cadastros.

Login de clientes, crypt_key e upgrade de hash de senha

Este é um dos pontos que mais me chamam para "apagar incêndio" pós-migração: o cliente migra tudo, faz o go-live, e nenhum cliente consegue logar. Quase sempre a causa está em dois lugares: a crypt_key errada (vista na seção de configuração) ou a falta de entendimento de como o M2 lida com hashes antigos do M1.

Por que as senhas dos clientes funcionam (ou não)

O Magento nunca armazena a senha em texto puro — guarda um hash com o algoritmo usado e a versão dele anexada ao próprio hash. O M1 gerava hashes com algoritmos antigos (MD5 e variações de SHA com salt). O M2 moderno usa, por padrão, Argon2ID13 quando a extensão Sodium do PHP está disponível (cai para SHA-256 se não estiver). A boa notícia: o M2 mantém a cadeia de versões do hash, então ele consegue validar uma senha antiga gerada no M1 — desde que a crypt_key esteja correta, porque é ela que entra no cálculo. Resumo prático: crypt_key certa = login funciona; crypt_key errada = base inteira travada.

Segundo a documentação de password hashing do Magento, o Commerce suporta múltiplos algoritmos (MD5, SHA-256 ou Argon2ID13); com a extensão Sodium presente, o Argon2ID13 é escolhido como algoritmo padrão de hashing, caso contrário o SHA-256. Como o Magento armazena, junto ao hash, as versões de algoritmo já aplicadas, ele reconstrói toda a cadeia de hash durante a verificação da senha — permitindo validar senhas geradas com algoritmos anteriores.

Fonte: Adobe Experience League

Upgrade gradual do algoritmo

Você não precisa (e não deve) forçar reset de senha de toda a base. O M2 faz upgrade transparente: na primeira vez que o cliente loga com a senha antiga validada com sucesso, o sistema re-hasheia a senha com o algoritmo atual (Argon2) e regrava. Para forçar o upgrade da camada externa do hash de toda a base de uma vez, existe o comando:

bin/magento customer:hash:upgrade

Cuidado de campo: já vi esse comando, em certas versões, deixar clientes sem conseguir logar quando rodado sem testar antes. Minha regra: nunca rode customer:hash:upgrade direto em produção sem validar login de um lote de clientes reais no staging migrado primeiro. Na maioria dos casos, o upgrade transparente no login já resolve, e o comando vira opcional.

Checklist de validação de login no dry run

• crypt_key: confirme que é byte-a-byte igual à do local.xml do M1.
• Login de cliente real: peça a senha de um cliente de teste do M1 e tente logar no ambiente migrado.
• Reset de senha: teste o fluxo de "esqueci minha senha" (e-mail transacional precisa estar configurado).
• Sodium/Argon2: confirme que a extensão Sodium está no PHP do servidor M2 (padrão desde PHP 7.2/7.3), senão o hashing cai para SHA-256.

Pós-migração: reindex, di:compile, static-content e modo de produção

Transferir os dados é metade do trabalho. Depois que o banco está populado, há um conjunto de passos operacionais obrigatórios sem os quais a loja M2 simplesmente não funciona — categorias vazias, busca sem resultados, frontend sem CSS. O artigo "clássico" de migração pula isso; em campo é o que mais derruba go-live.

1) Reindexação completa

Os dados vieram do M1, mas os índices do M2 (preço, estoque, URL de catálogo, fulltext/OpenSearch, EAV) estão vazios ou desatualizados. Sem reindex, categorias aparecem sem produtos e a busca não retorna nada:

bin/magento indexer:reindex

Em catálogos grandes isso também leva tempo — outro item para cronometrar no dry run.

2) Modo do indexer: Update on Save vs Update on Schedule

Há dois modos de indexação. Update on Save (realtime) reindexa na hora a cada alteração no Admin — degrada o MySQL e, em lojas grandes, pode levar horas. Update on Schedule usa Materialized Views (MView): grava as mudanças em uma changelog e o cron processa só os registros alterados em lote. Para produção séria, eu sempre uso schedule:

bin/magento indexer:set-mode schedule

Detalhe atual: no 2.4.8, o modo padrão de novos indexadores passou a ser Update by Schedule — mas vale conferir o estado de cada indexador com bin/magento indexer:show-mode após a migração, porque settings importados podem deixar alguns em realtime.

Conforme a documentação da Adobe, o comando bin/magento indexer:set-mode {realtime|schedule} [indexer] define o modo: realtime coloca os indexadores em "Update on Save" e schedule faz a indexação seguir o cron ("Update on Schedule"), que usa changelog/MView para processar apenas os registros alterados.

Fonte: Adobe Experience League

3) Compilar DI e gerar conteúdo estático (modo produção)

Em produção, o M2 roda código de Dependency Injection compilado e assets estáticos pré-gerados. Sem isso, a loja fica lenta (ou quebra) e o frontend aparece sem estilo. A sequência canônica de deploy é:

bin/magento maintenance:enable
bin/magento deploy:mode:set production
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy pt_BR en_US
bin/magento indexer:reindex
bin/magento cache:flush
bin/magento maintenance:disable

Ajuste os locales (pt_BR etc.) aos da sua loja. O setup:di:compile gera as classes de proxy/factory; o setup:static-content:deploy publica CSS/JS/imagens do tema em pub/static.

4) Ligar o cron e aquecer o cache

Durante a migração, o cron do M2 fica desligado. No go-live, ligue-o (é o cron que processa indexação agendada, e-mails, mensagens do RabbitMQ). E, com Varnish na frente, faça um cache warm-up (curl nas URLs do sitemap) para o primeiro visitante não pegar a loja "fria".

# crontab do usuário do webserver
* * * * * php /caminho/m2/bin/magento cron:run | grep -v "Ran jobs by schedule"

Preservar SEO: url_suffix, redirects 301 e import em massa de URLs

Esta é a seção que mais economiza dinheiro a longo prazo. Uma migração tecnicamente perfeita que quebra as URLs destrói o ranqueamento e o tráfego orgânico que você levou anos para construir. A estratégia tem três pilares: alinhar o url_suffix, preservar as URL keys e mapear redirects 301 para tudo que mudar. Para o trabalho completo de indexação, canonical, sitemap e dados estruturados depois do cutover, vale seguir em paralelo o guia de SEO Técnico para Magento 2.

O gotcha que quebra TODAS as URLs: o url_suffix

Antes de qualquer redirect, alinhe o sufixo de URL de produtos e categorias. Se o seu M1 usava .html no fim das URLs (/produto.html) e o M2 ficar com sufixo vazio (ou vice-versa), todas as suas URLs indexadas quebram de uma vez — não adianta nenhum redirect individual. Configure em Stores > Settings > Configuration > Catalog > Catalog > Search Engine Optimization:

• Product URL Suffix: tem que bater com o do M1 (ex.: .html ou vazio).
• Category URL Suffix: idem.
• Create Permanent Redirect for URLs if URL Key Changed: Yes.

Depois de alterar o sufixo, é obrigatório regenerar os rewrites e reindexar o índice de URL de catálogo (bin/magento indexer:reindex catalog_url_product catalog_url_category), senão as URLs antigas continuam apontando para o caminho errado.

Ativar redirects 301 automáticos

Segundo a documentação da Adobe, a loja pode ser configurada para gerar automaticamente um redirecionamento permanente sempre que a URL key de um produto ou categoria muda, bastando definir a opção "Create Permanent Redirect for URLs if URL Key Changed" como "Yes".

Fonte: Adobe Experience League

As regras geradas ficam visíveis em Marketing > SEO & Search > URL Rewrites. Mas atenção: isso só cobre mudanças feitas dentro do M2. Para os milhares de URLs antigas do M1 que mudaram de estrutura (sufixo, hierarquia de categoria, slugs), você precisa importar redirects em massa — e aí vem o problema.

Import em massa de 301: o M2 não tem isso no core admin

Não existe importação nativa de URL rewrites no admin do Magento 2 (você cria um a um, na mão). Para migração real, com milhares de redirects, há três abordagens:

1. Extensão de redirect import via CSV: a opção mais rápida para a equipe de marketing; várias do Marketplace leem uma planilha de "request_path → target_path".
2. Script PHP usando o repositório/factory de UrlRewrite: o caminho "certo" para devs — você usa Magento\UrlRewrite\Model\UrlPersistInterface / UrlRewriteFactory para persistir em massa, respeitando a lógica de domínio do M2.
3. Insert direto na tabela url_rewrite: mais rápido para volumes enormes, mas pula validações — use com cuidado e sempre seguido de cache:flush.

Uma linha típica da tabela url_rewrite para um 301:

INSERT INTO url_rewrite
  (entity_type, entity_id, request_path, target_path, redirect_type, store_id, description, is_autogenerated)
VALUES
  ('custom', 0, 'categoria-antiga.html', 'nova-categoria.html', 301, 1, 'Migracao M1', 0);

O redirect_type=301 é o que importa; request_path é a URL antiga (sem barra inicial), target_path é o destino. Depois do import, rode o Catalog URL Rewrites generate / reindex do catalog_url e um cache:flush.

301 vs 302: use o código certo

Change of Address: só para troca de domínio

A ferramenta Change of Address do Search Console serve exclusivamente quando você muda de domínio (ex.: loja.com.br → novaloja.com.br). Se você está só mudando o caminho das URLs dentro do mesmo domínio (que é o caso típico de migração M1→M2 no mesmo site), não use Change of Address — bastam os 301. Usar a ferramenta no cenário errado confunde o Google.

O Google recomenda manter os redirects pelo maior tempo possível, geralmente por pelo menos 1 ano, para que todos os sinais sejam transferidos às novas URLs; usar redirects permanentes server-side (301 e 308); e manter as cadeias de redirect curtas (idealmente até 3 hops, abaixo de 5; o Googlebot segue até 10).

Fonte: Google Search Central

SSL/HTTPS, base_url e mixed content na nova loja

Muita migração quebra não nas URLs, mas no protocolo. Se o M1 antigo servia parte do site em HTTP e você sobe o M2 inteiramente em HTTPS (como deve), há dois cuidados que evitam perda de SEO e o cadeado quebrado.

base_url seguro e force HTTPS

Configure em Stores > Configuration > General > Web as duas Base URLs (Unsecure e Secure, ambas com https:// em produção) e ative "Use Secure URLs on Storefront" e "Use Secure URLs in Admin" = Yes. Pela CLI, fica versionável e à prova de erro de digitação:

bin/magento config:set web/unsecure/base_url https://www.sualoja.com.br/
bin/magento config:set web/secure/base_url  https://www.sualoja.com.br/
bin/magento config:set web/secure/use_in_frontend 1
bin/magento config:set web/secure/use_in_adminhtml 1
bin/magento config:set web/url/redirect_to_base 1
bin/magento cache:flush

Mixed content e o impacto em SEO

O mixed content (página HTTPS carregando imagem/JS/CSS em HTTP) faz o navegador bloquear recursos e quebra o cadeado — e ainda prejudica a experiência que o Google avalia. As fontes típicas em migração são URLs absolutas http:// gravadas no conteúdo CMS, em atributos de produto WYSIWYG e em banners do Page Builder, que vieram do M1. Faça uma varredura no banco e no conteúdo e troque http:// por https:// (ou por URLs relativas / {{media url=...}}).

Dois redirects sobrepostos

Lembre que numa migração você pode ter duas mudanças simultâneas: protocolo (http→https) e caminho (URL antiga→nova). Resolva ambos com 301 server-side, encadeando o mínimo possível — idealmente um único 301 que já leve da URL antiga em HTTP direto para a URL nova em HTTPS, sem hops intermediários. Cadeia longa de redirect dilui sinal e atrasa o crawl.

Extensões e tema: compatibilidade, Hyvä (agora free) e o declínio do PWA Studio

Como vimos, extensões M1 não funcionam no M2. O primeiro passo do plano oficial é revisar as extensões do site atual e decidir, uma a uma: existe equivalente nativo no M2? Existe no Marketplace? Ou é preciso reconstruir?

Como auditar a compatibilidade de cada extensão M2

Achar o "equivalente M2" é só o começo. Antes de comprar/instalar, eu audito:

• Versão de PHP suportada: confira no composer.json da extensão a constraint de php. Em 2.4.8 você precisa de extensão compatível com PHP 8.3/8.4 — extensões paradas em 8.1 vão dar erro de instalação ou de runtime.
• Conflitos de preference/plugin: duas extensões que fazem <preference> para a mesma classe brigam (a última vence, a outra some). Plugins na mesma before/around/after de um método podem se anular. Rode bin/magento setup:di:compile no staging — ele reclama de preferences duplicadas.
• Compatibilidade com o tema escolhido: este é o gotcha grande, abaixo.

O gotcha Hyvä: extensões com frontend Knockout não funcionam direto

Muitas extensões M2 do Marketplace renderizam o frontend com Knockout/UI Components — exatamente o que o Hyvä removeu. Resultado: a extensão instala, o backend funciona, mas o componente de frontend não aparece no tema Hyvä sem um compatibility module. Existe um ecossistema de módulos de compatibilidade Hyvä para as extensões mais populares, mas para extensões de nicho você pode ter que escrever a ponte — custo real que precisa entrar no orçamento da migração.

Escolha de tema (frontend)

Como o storefront é reconstruído do zero, a escolha do tema define custo, performance e manutenção dos próximos anos — e impacta diretamente os Core Web Vitals:

Hyvä: agora open source — a notícia que muda a decisão

Aqui está a atualização que separa um guia datado de um atual: o que durante anos custou uma licença vitalícia de ~EUR 1.000 por domínio mudou. Desde novembro de 2025, o Hyvä Theme foi relicenciado como open source e gratuito (sob OSL 3.0 + AFL 3.0, o mesmo modelo do Magento Open Source). Na prática, o custo de licença do tema base saiu da conta da migração. Continuam proprietários e pagos os produtos premium do ecossistema — Hyvä Checkout, Hyvä Enterprise, Hyvä Commerce e o Hyvä UI (kit de componentes, cerca de EUR 250 por loja). O Hyvä é construído sobre Tailwind CSS e Alpine.js, eliminando Knockout, RequireJS e jQuery do storefront, e mantém convenções como o layout.xml — reduzindo drasticamente requisições e peso de página frente ao Luma, o que costuma ser decisivo para passar nos Core Web Vitals.

Em sua documentação de Technical Vision, o time do Hyvä define o projeto como "the version of Luma we wished Magento had built" e afirma que "got rid of the parts we would gladly live without (Knockout/Require/jQuery)". Já em novembro de 2025, a empresa anunciou o relicenciamento do Hyvä Theme como open source e gratuito (OSL 3.0 + AFL 3.0), mantendo proprietários os produtos Hyvä Checkout, Enterprise e Commerce.

Fonte: Hyvä Themes (Technical Vision) e Hyvä Themes (anúncio open source)

PWA Studio: por que eu hesito em recomendar para projeto novo

O PWA Studio usa arquitetura headless (React + GraphQL), com a storefront de referência Venia (venia-ui, peregrine, venia-concept). O ponto que um especialista precisa dizer em 2026: a Adobe moveu o PWA Studio para maintenance mode em 2024 — sem novas features, apenas patches de segurança e compatibilidade — e passou a recomendar o Edge Delivery Services como solução de storefront para projetos novos. Não está deprecado, mas o investimento e o ecossistema diminuíram. Para quem quer headless hoje, costumo avaliar Vue Storefront/Alokai ou Hyvä React antes do PWA Studio, por ecossistema mais vivo e menor risco de manutenção.

Extensões com tabelas próprias: a classe AbstractDelta

Se uma extensão M1 criou tabelas próprias no banco, o delta padrão não rastreia essas tabelas — você precisa ensinar a ferramenta. São três passos: (1) registrar as tabelas no deltalog.xml para que triggers sejam instalados nelas; (2) criar uma classe de delta estendendo Migration\App\Step\AbstractDelta; (3) declarar a classe na seção delta do config.xml. O esqueleto da classe:

<?php
namespace Vendor\Migration\Step\MyExtension;

use Migration\App\Step\AbstractDelta;

class Delta extends AbstractDelta
{
    /**
     * Caminho do map.xml que descreve o mapeamento das tabelas da extensão
     */
    protected function getMapFile()
    {
        return 'etc/my-extension/map.xml';
    }

    /**
     * Lista das tabelas (delta documents) que esta classe migra incrementalmente
     */
    protected function getDocumentList()
    {
        return [
            'my_extension_table' => 'my_extension_table',
        ];
    }
}

Sem isso, os registros que a extensão gravar no M1 durante a janela de migração simplesmente não chegam ao M2 — um furo silencioso que só aparece dias depois.

Runbook de cutover: DNS TTL, smoke tests e ponto de não-retorno

Migração bem-sucedida é migração ensaiada e com runbook escrito. A sequência oficial de planejamento (create-plan) tem sete passos, mas o que evita o desastre no dia D é um roteiro de virada com horários e um checklist pós-go-live. Vou detalhar os dois.

Pré-requisitos antes de tocar na ferramenta

• Instale o M2 conforme os system requirements, espelhando a topologia do M1.
• Backup do banco do M2 logo após a instalação ("Back up or dump your Magento 2 database as soon as possible").
• Acesso de rede garantido entre os bancos M1 e M2.
• Pare a atividade no admin do M1 (exceto gestão de pedidos) antes e durante a migração.
• NÃO inicie os cron jobs do M2 durante a migração ("Do not start Magento 2 cron jobs").

Conforme a documentação de pré-requisitos da Adobe, durante a migração você deve fazer backup do banco do M2 o quanto antes, garantir acesso de rede entre os bancos M1 e M2 e não iniciar os cron jobs do Magento 2 — em suas palavras, "Do not start Magento 2 cron jobs". A orientação de parar as atividades no admin do M1 (exceto gestão de pedidos) aparece no plano de migração (create-plan).

Fonte: Adobe Experience League

O runbook de cutover (com tempos)

DNS vs. backend switch: dois jeitos de virar

Há duas estratégias de cutover de rede, e elas têm trade-offs diferentes. Troca de DNS é simples mas depende da propagação (por isso o TTL baixo). Backend switch no Varnish/load balancer (mudar para qual origem o proxy aponta) é instantâneo e reversível em segundos, sem esperar DNS — minha preferência quando a infra permite, porque o rollback é imediato. Se você usa CDN/Varnish na frente, prefira o backend switch e deixe o DNS como segunda camada.

Checklist pós-go-live (smoke tests obrigatórios)

• 1 pedido real ponta a ponta: adicionar ao carrinho, checkout, pagamento aprovado em modo produção (não sandbox), pedido criado no admin.
• E-mail transacional: confirmação de pedido chegou (SMTP/serviço de e-mail configurado).
• Busca: OpenSearch indexado, busca retorna resultados, categorias com produtos.
• Login de cliente: um cliente migrado consegue logar (valida crypt_key/hash).
• Reindex e cron: indexadores "valid", cron rodando, fila do RabbitMQ consumindo.
• Cache quente: Varnish/FPC servindo HIT nas páginas principais.
• SEO técnico: robots.txt liberando crawl (sem o Disallow: / que ficou do staging!), sitemap.xml gerado e submetido, canonical/HTTPS corretos.
• Monitoramento: acompanhar 404s, logs de erro e os redirects 301 nas primeiras horas; se mudou de domínio, registrar o novo no Search Console.

Rollback honesto: defina o ponto de não-retorno

O motivo de o M1 continuar de pé é justamente o rollback: se algo crítico falhar no cutover, você reverte o backend/DNS de volta para o M1 em minutos. Mas há um trade-off que ninguém gosta de falar: todo pedido criado no M2 após a virada se perde se você voltar para o M1 (o M1 não conhece esses pedidos). Por isso o rollback é viável nos primeiros minutos/horas, antes do volume de pedidos no M2 ficar relevante. Eu sempre defino com o cliente um ponto de não-retorno explícito no runbook — por exemplo, "após X pedidos ou Y horas no M2, não há rollback; problemas serão corrigidos no próprio M2 com hotfix". Sem esse ponto definido por escrito, a decisão de rollback vira pânico na madrugada.

Staging e teste de carga antes do go-live

Eu nunca faço go-live sem um ambiente de staging idêntico à produção, onde rodo o dry run completo e cronometro cada step. Aproveito o staging para um teste de performance comparativo: meço TTFB/LCP do M2 em staging e comparo com a baseline do M1 — não quero migrar e regredir em Core Web Vitals. Se o LCP do M2 com FPC+Varnish+Hyvä não estiver claramente melhor que o do M1, algo está errado (cache não aquecido, imagem não otimizada, JS de extensão pesando) e isso se resolve antes do cutover, não depois. Aproveite também para já entrar na nova loja com as práticas de segurança e hardening aplicadas.

Adobe Commerce ou Magento Open Source: preço, Page Builder, BI e IA

A migração é o momento ideal para revisitar a edição. Adobe Commerce e Magento Open Source compartilham o mesmo núcleo: mesmo template engine, mesma arquitetura de módulos, mesmo fluxo de checkout. A diferença está no que a edição paga adiciona — e, sim, no preço.

Preço: o que a Adobe não publica em tabela

O Adobe Commerce não tem preço de prateleira — a licença é cotada conforme o GMV (receita bruta) anual, o ticket médio e o tier de infraestrutura. Como regra geral de mercado (não um número oficial da Adobe), os tiers de entrada costumam começar na casa das dezenas de milhares de dólares por ano e escalam com o GMV; a versão Cloud (PaaS) sai mais cara que a on-premises porque inclui a infraestrutura gerenciada. O valor exato é sempre sob cotação com a Adobe/parceiro — por isso, para a maioria das lojas B2C de pequeno e médio porte no Brasil, o número já elimina o Commerce da conta.

Page Builder NÃO é exclusivo do Commerce

Vale corrigir uma percepção comum: o Page Builder (editor de conteúdo arrasta-e-solta) está disponível no Magento Open Source desde a versão 2.4.3, como ferramenta nativa de CMS unificada entre as duas edições. Ou seja, você não precisa pagar Commerce só por causa do Page Builder — alguns recursos avançados de conteúdo dinâmico seguem exclusivos do Commerce, mas o construtor visual em si está no Open Source.

Os diferenciais de IA e BI do Commerce

• Live Search: busca com IA (ranqueamento inteligente, faceting dinâmico, sinônimos e tolerância a erro de digitação), entregue como extensão SaaS e sem licença separada — mas somente para Adobe Commerce. No Open Source, o equivalente é contratar Algolia, Klevu ou Doofinder.
• Product Recommendations (Adobe Sensei): recomendações personalizadas por IA ("quem comprou também levou", "recomendado para você", "em alta", "vistos recentemente"), analisando comportamento e histórico em tempo real. Exclusivo do Commerce.
• Adobe Commerce Intelligence (BI): plataforma de business intelligence com dashboards e relatórios de receita, coorte e LTV — para decisão orientada a dados sem montar um stack de BI à parte.

Conforme a documentação B2B da Adobe, recursos como Shared catalogs e Negotiable Quotes estão disponíveis somente para lojas Commerce configuradas para suportar company accounts — em suas palavras, "available only for Commerce stores configured to support Company accounts". Já o Page Builder, segundo a documentação oficial de Page Builder, está disponível por padrão tanto no Adobe Commerce quanto no Magento Open Source a partir da versão 2.4.3.

Fonte: Adobe Experience League (B2B) e Adobe Experience League (Page Builder)

Minha recomendação prática

Para a maioria das lojas B2C de pequeno e médio porte no Brasil, o Magento Open Source entrega tudo o que é preciso — Page Builder incluso, e busca/recomendação de IA resolvidas com Algolia/Klevu — desde que você assuma a responsabilidade de manter segurança e atualizações em dia (justamente o erro que levou ao desastre do M1). Já operações B2B (catálogos negociados, cotações, múltiplas company accounts) ou que querem Live Search + recomendações Sensei + BI de fábrica costumam justificar o Adobe Commerce — quando o GMV comporta a licença. Como o core é o mesmo, dá para começar no Open Source e migrar para Commerce depois, sem nova re-plataforma. (Sobre profiling de performance: Blackfire aparece integrado ao ambiente do Adobe Commerce on cloud infrastructure, mas não é um recurso "ligado" do on-premises e não deve pesar na decisão de edição — profiling em projetos Open Source se monta à parte com Blackfire, Tideways ou New Relic.)