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: segurança, performance, recursos modernos e suporte

Segurança é o motivo número um, mas não é o único. Migrar para Magento 2 / Adobe Commerce coloca a loja sobre uma stack moderna, com suporte ativo e recursos nativos que no Magento 1 só existiam via extensões frágeis. A versão atual, Adobe Commerce / Magento Open Source 2.4.8, exige uma stack completamente diferente da do M1:

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, que segue presente em patches anteriores. A Adobe dá suporte apenas às combinações de requisitos listadas na documentação oficial de system requirements. Rodar fora dessas combinações — ou com dependências como PHP/MySQL já em fim de vida — coloca você na mesma situação de risco do M1.

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. Isso permite planejar atualizações com previsibilidade, algo impossível em uma plataforma já morta. Importante: a Adobe não fornece correções para dependências de terceiros (PHP, MySQL etc.) que cheguem ao fim de vida dentro dessa janela — por isso manter a stack atualizada continua sendo responsabilidade do lojista.

Recursos nativos e performance

O Magento 2 traz, de fábrica, arquitetura de cache em camadas (full page cache nativo, Varnish), indexadores assíncronos, fila de mensagens (RabbitMQ) para processamento em background e APIs robustas (REST e GraphQL) que viabilizam storefronts headless. Recursos que no M1 dependiam de dezenas de módulos de terceiros passam a ser parte do core, reduzindo superfície de bug e custo de manutenção. Essa base moderna também é o que torna viável atingir bons números de Core Web Vitals — algo praticamente inalcançável no M1.

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.

O que isso significa na prática

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).
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.

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: modos settings, data e delta

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). 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:

A sintaxe geral aceita duas flags importantes:

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

• -r | --reset: reinicia a migração do começo. Use em ambiente de testes/dry run.
• -a | --auto: impede a migração de parar quando encontra erros de integrity check.

Os três estágios internos de cada step

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.
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.

A ferramenta salva o progresso conforme executa, o que permite retomar de onde parou em vez de recomeçar uma migração de horas.

Segundo a documentação da Adobe, o Data Migration Tool foi projetado para transferir os dados nesta sequência — settings, data e, por último, as mudanças incrementais (delta) — e a própria Adobe recomenda fortemente respeitar essa ordem. O caminho absoluto para o config.xml é um argumento obrigatório em todos os comandos.

Fonte: Adobe Experience League

Configuração e arquivos de mapeamento (config.xml e map.xml)

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 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.

Como configurar

O fluxo básico é copiar o arquivo de distribuição e editar com seus dados:

cp config.xml.dist config.xml

Você pode, alternativamente, copiar para um módulo customizado em app/code/Vendor/Migration/etc/<edition>/<version>/config.xml — recomendado para versionar suas customizações de mapeamento no Git. No config.xml é preciso informar:

• Banco de origem (M1): host, nome do banco e usuário.
• Banco de destino (M2): host, nome do banco e usuário.
• Encryption key: a chave de criptografia que está no app/etc/local.xml do Magento 1 (dentro da tag <key>), informada na tag <crypt_key> do config.xml.

Por que o mapeamento importa

O map.xml resolve as diferenças entre as estruturas de tabela do M1 e do M2 — renomeações de campos, campos que não devem ser migrados e tabelas ignoradas. Quando o Integrity Check acusa incompatibilidade, é no arquivo de mapeamento que você ajusta as regras. Para extensões que criaram tabelas próprias no M1, esse trabalho é mais profundo, como veremos 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 automaticamente e o que exige retrabalho manual

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 manual de mídia

Os arquivos de mídia não são migrados pela ferramenta. Eles precisam ser copiados manualmente do diretório de mídia do M1 para o do M2. Em lojas com catálogos grandes, planeje essa transferência com cuidado (rsync, janela de banda) porque pode levar horas. Um comando típico:

rsync -avz magento1-root/media/ magento2-root/pub/media/

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

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 é não criar novas entidades no M2 antes de concluir a migração; deixe a ferramenta popular o catálogo e só depois faça ajustes e novos cadastros.

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

Preservar SEO: URL keys, redirects 301 e migração 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 dois pilares: preservar as URL keys sempre que possível 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.

Ativar redirects 301 automáticos no Magento 2

O Magento 2 pode gerar redirects permanentes automaticamente quando você altera a URL key de um produto ou categoria. Para ativar, vá em Stores > Settings > Configuration > Catalog > Catalog > Search Engine Optimization e defina:

• Create Permanent Redirect for URLs if URL Key Changed: Yes.

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, onde você também pode criar rewrites manuais escolhendo o tipo Permanent (301) ou Temporary (302).

301 vs 302: use o código certo

Para mudanças permanentes — que é o caso de uma migração — o Google recomenda redirect permanente server-side (301 ou 308). Os temporários (302/303/307) não são usados como sinal de canonicalização e não transferem autoridade.

O checklist do Google para mudança de URLs

• Mapeamento: prepare uma planilha de URLs antigas → novas.
• Redirects server-side: configure 301/308 das antigas para as novas.
• Sitemap: submeta o novo sitemap no Search Console.
• Change of Address: use a ferramenta se houver mudança de domínio.
• Monitoramento: acompanhe tráfego nas URLs antigas e novas.
• Cadeias curtas: redirecione direto ao destino final; se não der, mantenha a cadeia idealmente em até 3 hops e abaixo de 5 (o Googlebot segue até 10).
• Duração: mantenha os redirects pelo maior tempo possível.

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; e usar redirects permanentes server-side (301 e 308) sempre que tecnicamente viável.

Fonte: Google Search Central

Extensões e escolha de tema: Luma, Hyvä, PWA ou custom

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?

Extensões com tabelas próprias

Se uma extensão M1 criou tabelas próprias no banco, há trabalho extra para migrar esses dados. É necessário:

1. Rastrear as mudanças adicionando as tabelas ao deltalog.xml.
2. Criar uma classe de delta estendendo Migration\App\Step\AbstractDelta.
3. Adicionar a classe na seção delta do config.xml.

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ä: o Luma que o Magento deveria ter construído

O Hyvä é um frontend para Magento 2 construído sobre Tailwind CSS e Alpine.js que elimina Knockout, RequireJS e jQuery do storefront. O próprio time o descreve como "the version of Luma we wished Magento had built", mantendo convenções como o layout.xml e reduzindo drasticamente o número de requisições e o peso de página frente ao Luma — o que costuma ser decisivo para passar nos Core Web Vitals.

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)".

Fonte: Hyvä Themes

PWA Studio / headless

O PWA Studio é definido pela Adobe como "a set of tools and libraries that let you develop, deploy, and maintain a PWA storefront on top of an Adobe Commerce or Magento Open Source backend". Usa arquitetura headless (frontend separado do backend via GraphQL). A storefront de referência é a Venia, com os pacotes venia-ui (componentes React), peregrine (estado/dados) e venia-concept (template de projeto). É a opção de maior custo e complexidade, justificada quando a experiência app-like e a separação total de camadas são requisitos de negócio.

Planejamento, dry run, delta e plano de rollback

Migração bem-sucedida é migração ensaiada. A sequência oficial de planejamento (create-plan) tem sete passos, e cada um existe por um motivo concreto.

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").

A sequência de go-live

1. Revisar extensões — decidir equivalentes/reconstrução.
2. Construir e preparar a loja M2 — tema, extensões, integrações.
3. Dry run em ambiente de teste (use a flag -r para recomeçar quantas vezes precisar).
4. Iniciar a migração — settings + data.
5. Ajustar dados migrados se necessário.
6. Atualizar dados incrementais (delta) — captura clientes e pedidos novos criados durante o processo.
7. Go-live — cutover.

Por que o delta muda o jogo

O grande valor desse fluxo é permitir congelar o admin do M1 enquanto o storefront M1 continua vendendo. Durante a migração, a Adobe orienta interromper todas as atividades no admin do M1 exceto a gestão de pedidos — envio, faturas e notas de crédito —, enquanto as operações no storefront M1 seguem permitidas. Você roda a migração de data, e os pedidos e clientes que entrarem nesse intervalo são capturados depois pelo modo delta. Isso reduz a janela de indisponibilidade a praticamente zero do ponto de vista do cliente final.

Staging e rollback

Eu nunca faço go-live sem dois itens: um ambiente de staging idêntico à produção, onde o dry run completo é executado, e um plano de rollback com backups do banco feitos imediatamente antes do go-live. Se algo der errado no cutover, você precisa conseguir voltar ao M1 operacional em minutos, não em horas. Aproveite também o cutover para já entrar na nova loja com as práticas de segurança e hardening aplicadas, em vez de deixar para depois.

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

Adobe Commerce ou Magento Open Source: qual escolher

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 sobre esse core.

Recursos exclusivos de Commerce

Sobre o mesmo core, o Adobe Commerce adiciona B2B nativo (company accounts, shared catalogs, negotiable quotes, requisition lists), customer segmentation, content staging, visual merchandising, suporte oficial Adobe e patching de segurança automatizado. Recursos B2B como Shared catalogs e Negotiable Quotes são oficialmente exclusivos das lojas Commerce configuradas para company accounts.

Uma palavra sobre profiling e o Adobe Commerce Cloud

Vale corrigir um mal-entendido comum: o Blackfire não é um recurso "embutido e ligado" do Adobe Commerce on-premises. Ele aparece como ferramenta de profiling associada ao ambiente do Adobe Commerce on cloud infrastructure, onde há integração documentada para análise de performance, mas seu uso depende de configuração e de assinatura própria do Blackfire. Em projetos Open Source ou on-premises, profiling de performance normalmente é montado à parte (Blackfire, Tideways, New Relic, Xdebug em ambiente de teste).

Conforme a documentação da Adobe, recursos B2B 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".

Fonte: Adobe Experience League

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 — 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, com catálogos negociados, cotações e múltiplas company accounts, costumam justificar o investimento no Adobe Commerce, porque reconstruir esses recursos no Open Source sai caro e frágil. A boa notícia: como o core é o mesmo, é possível começar no Open Source e migrar para Commerce depois, sem nova re-plataforma.