DocumentaçãoCommerceCommerce na nuvem

Atualizar versão do Commerce

Última atualização: 1 de setembro de 2026

Criado para:

  • Admin
  • Desenvolvedor

Você pode atualizar a base de código do Adobe Commerce para uma versão mais recente. Antes de atualizar o ambiente, verifique os requisitos de sistema no guia Instalação para obter os requisitos de versão de software mais recentes.

Dependendo do tipo de ambiente (Desenvolvimento, Preparo ou Produção), suas tarefas de atualização podem incluir o seguinte:

  • Atualize extensões de terceiros para a versão mais recente com suporte.

  • Atualize o arquivo .magento/services.yaml com as versões de serviço necessárias para MariaDB (MySQL), OpenSearch, RabbitMQ e Redis ou Valkey, para que permaneçam compatíveis com a versão de destino do Adobe Commerce.

    • Para ramificações de desenvolvimento/integração/PR, essas alterações são usadas diretamente como parte da configuração do ambiente.
    • Para ambientes de preparo e produção profissionais, o Suporte da Adobe Commerce executa a instalação ou atualização real do serviço, mas você ainda deve manter .magento/services.yaml atualizado, completo e válido, pois seu conteúdo é validado durante a implantação.

  • Atualize o arquivo .magento.app.yaml com novas configurações para ganchos e variáveis de ambiente.

TIP
Antes de iniciar uma atualização ou um processo de patch, crie uma ramificação ativa do ambiente de integração e faça check-out da nova ramificação para a estação de trabalho local. Dedicar uma ramificação à atualização ou ao processo de patch ajuda a evitar interferência com o trabalho em andamento.

Suporte a serviços profissionais

Para solicitar e concluir uma atualização de serviço Pro em Preparo ou Produção, siga estas etapas:

  1. Para instalar ou atualizar os serviços somente nos ambientes Staging e Production, envie um tíquete de Suporte da Adobe Commerce.

    No ticket, especifique as alterações de serviço necessárias, inclua os arquivos .magento.app.yaml e .magento/services.yaml atualizados e observe a versão do PHP de destino.

    A versão do PHP, as atualizações do Composer, as extensões e as configurações do ambiente são alterações de autoatendimento. O Adobe pode precisar atualizar o agente New Relic para compatibilidade de versão do PHP. Consulte configurações do PHP em Configuração do aplicativo.

    note important
    IMPORTANT
    Ao selecionar o campo Environment no formulário de tíquete, use a nomenclatura de ambiente do Adobe. Por exemplo, selecione Preparo mesmo se você chamar esse ambiente de Desenvolvimento internamente. Você pode mencionar seu nome interno na descrição, mas o campo Environment deve usar a nomenclatura da Adobe.

  2. Confirme o agendamento da atualização por meio do processo de duas partes da Adobe: primeiro você confirma a data e a hora solicitadas e, em seguida, o suporte a envia à equipe de infraestrutura para confirmação final.

    As alterações na produção (somente Pro) exigem um aviso de pelo menos dois dias úteis, exceto nos finais de semana. Por exemplo, a equipe de infraestrutura em nuvem deve reconhecer uma atualização de segunda-feira até a quarta-feira anterior. Espere um lead time adicional durante o pico da demanda. Para evitar atrasos, responda à solicitação inicial pelo menos 48 horas antes da janela. A atualização não é considerada programada até que você receba a confirmação final.

    note
    NOTE
    Fornecer janelas de manutenção em UTC. As atualizações de preparo não são agendadas com antecedência e normalmente são concluídas no mesmo dia da solicitação.
    Após uma atualização do RabbitMQ, reimplante o ambiente para reinicializar as filas de mensagens.

  3. Valide a atualização em um ambiente de Preparo ou Integração antes de agendá-la na Produção.

    Problemas causados por módulos de terceiros, código personalizado ou compatibilidade de dependência geralmente surgem durante a reimplantação que segue uma atualização de serviço. Para validar várias atualizações de serviço, uma ordem razoável é Valkey ou Redis, RabbitMQ, OpenSearch e MariaDB. Esta não é uma sequência obrigatória. Os upgrades de bancos de dados têm o maior impacto operacional e merecem a maior cautela.

    A Adobe não garante a duração exata de uma janela de manutenção de Produção com antecedência, pois o tempo depende do ambiente e dos serviços envolvidos. Use o tempo que leva a atualização em preparo como uma estimativa prática ao planejar a janela Produção.

  4. Reimplante o ambiente depois que o Adobe concluir a atualização do serviço para que a alteração entre em vigor, mesmo que a versão do aplicativo Adobe Commerce não seja alterada.

    Se a atualização incluir o OpenSearch, também planeje uma reindexação completa. A Adobe não pode garantir tempo de inatividade zero para uma atualização de serviço. Portanto, planeje uma janela de manutenção que permita tempo para reimplantar, reindexar, se necessário, e validar a loja e o administrador antes de reabrir o site.

Disponibilidade do cliente durante atualizações

Um representante de sua equipe ou parceiro de implementação deve estar disponível online durante a janela de atualização de Produção agendada. O agendamento durante um período de tráfego baixo não tira as mãos da atualização. O Adobe gerencia a atualização da infraestrutura em nuvem, mas não pode validar o comportamento do aplicativo, as integrações, o código personalizado ou os fluxos de trabalho de negócios.

O representante disponível deve poder:

  • Monitorar a loja e as transações comerciais críticas durante e após a atualização.
  • Responda às perguntas do Suporte da Adobe ou da equipe de Infraestrutura em Nuvem.
  • Confirme se as integrações, extensões, personalizações, trabalhos cron, filas e outras funções específicas do cliente estão funcionando conforme o esperado.
  • Validar fluxos de trabalho críticos para os negócios, como check-out, exibições de catálogo, pesquisa, logon e processamento de pedido.
  • Relatar comportamento inesperado prontamente, enquanto o contexto de atualização e os logs ainda estão disponíveis.
TIP
Para projetos Pro, as atualizações de serviço na produção também exigem programação antecipada e um processo de confirmação em duas partes com o suporte da Adobe. Consulte Suporte a serviços profissionais.

Modo de manutenção

O modo de manutenção não substitui a disponibilidade do cliente. O modo de manutenção bloqueia o acesso da loja, mas não valida serviços de aplicativos, integrações, filas, trabalhos cron, check-out ou outras funções específicas do cliente.

Se o trabalho planejado exigir o modo de manutenção, coordene o uso com o Suporte da Adobe e siga as instruções para essa atualização. Depois, confirme se a loja e os workflows críticos estão funcionando normalmente antes de considerar o trabalho como concluído.

Arquivos de configuração

Para levar em conta as alterações nas definições de configuração padrão do Adobe Commerce na infraestrutura em nuvem ou no aplicativo, atualize os arquivos de configuração do projeto antes de atualizar o aplicativo. Os padrões mais recentes podem ser encontrados no repositório GitHub da magento-cloud.

composer.json

Antes de atualizar, sempre verifique se as dependências no arquivo composer.json são compatíveis com a versão do Adobe Commerce.

Para atualizar o arquivo composer.json para o Adobe Commerce versão 2.4.4 e posterior**:

  1. Adicionar o seguinte allow-plugins à seção config:

    code language-json 
    "config": {
   "allow-plugins": {
      "dealerdirect/phpcodesniffer-composer-installer": true,
      "laminas/laminas-dependency-plugin": true,
      "magento/*": true
   }
},

  2. Adicionar o seguinte plug-in à seção require:

    code language-json 
    "require": {
    "magento/composer-root-update-plugin": "^2.0.3"
},

  3. Adicionar o seguinte componente à seção extra:component_paths:

    code language-json 
    "extra": {
   "component_paths": {
      "tinymce/tinymce": "lib/web/tiny_mce_5"
   },
},

  4. Salve o arquivo. Não confirme ou envie alterações para sua ramificação ainda.

  5. Continue com o processo de atualização.

Backup de ambiente

A Adobe recomenda criar um backup da instância antes de uma atualização. Use as etapas a seguir para fazer backup dos ambientes de integração, de preparo e de produção.

Para fazer backup do banco de dados e do código do ambiente de integração:

  1. Crie um backup local do banco de dados remoto.

    code language-bash 
    magento-cloud db:dump
    note
    NOTE
    O comando magento-cloud db:dump executa o comando mysqldump com o sinalizador --single-transaction, que permite fazer backup do banco de dados sem bloquear as tabelas.

  2. Faça backup do código e da mídia.

    code language-bash 
    php bin/magento setup:backup --code [--media]

    Opcionalmente, você pode omitir [--media] se tiver um grande número de arquivos estáticos que já estão no controle do código-fonte.

Para fazer backup do banco de dados do ambiente de Preparo ou Produção antes de implantar:

  1. Use o SSH para fazer logon no ambiente remoto.

  2. Criar um despejo de banco de dados. Para escolher um diretório de destino para o despejo do banco de dados, use a opção --dump-directory.

    code language-bash 
    vendor/bin/ece-tools db-dump

    A operação de despejo cria um arquivo morto dump-<timestamp>.sql.gz no diretório do projeto remoto. Consulte Fazer backup do banco de dados.

Atualização de aplicativo

Examine as informações das versões de serviço para obter os requisitos de versão de software mais recentes antes de atualizar seu aplicativo.

Para atualizar a versão do aplicativo:

  1. Na estação de trabalho local, altere para o diretório do projeto.

  2. Defina a restrição de versão para a versão de atualização de destino. Esta etapa só será necessária se a versão de destino estiver fora da restrição existente.

    code language-bash 
    composer require-commerce "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    note
    NOTE
    Você deve usar a sintaxe de restrição de versão para atualizar o pacote ece-tools com êxito. Você pode localizar a restrição de versão no arquivo composer.json da versão do modelo de aplicativo que você está usando para a atualização.

  3. Atualize seu arquivo composer.json com a versão principal de atualização do Commerce.

    code language-bash 
    composer require-commerce magento/product-enterprise-edition 2.4.8 --no-update

  4. Se você estiver usando B2B, atualize seu arquivo composer.json com a versão com suporte para Commerce.

    code language-bash 
    composer require-commerce magento/extension-b2b 1.5.2 --no-update

  5. Atualizar dependências do projeto.

    code language-bash 
    composer update

  6. Revise os patches atualmente aplicados:

    • Se houver patches instalados no diretório m2-hotfixes, envie um tíquete de Suporte da Adobe Commerce e trabalhe com o Suporte da Adobe Commerce para verificar quais patches ainda podem ser aplicados à nova versão. Remova os patches não aplicáveis do diretório m2-hotfixes.

    • Se houver [Patches de Qualidade] aplicados no arquivo .magento.env.yaml, verifique se eles ainda podem ser aplicados à nova versão. Remova os patches não aplicáveis da seção QUALITY_PATCHES do arquivo .magento.env.yaml.

    Método 1: Verifique as versões aplicáveis nas notas de versão de Patches de Qualidade

    Método 2: Exibir patches e status disponíveis

    Método 3: Pesquisar patches

  7. Adicionar, confirmar e enviar alterações de código.

    code language-bash 
    git add -A
    code language-bash 
    git commit -m "Upgrade"
    code language-bash 
    git push origin <branch-name>

    git add -A é necessário para adicionar todos os arquivos alterados ao controle do código-fonte devido à forma como o Composer realiza marshaling nos pacotes base. Os arquivos de marshaling de composer install e composer update do pacote base (magento/magento2-base e magento/magento2-ee-base) para a raiz do pacote.

    Os arquivos que o Composer empacota pertencem à nova versão do Adobe Commerce, para substituir a versão desatualizada desses mesmos arquivos. Atualmente, o empacotamento está desativado no Adobe Commerce, portanto, você deve adicionar os arquivos empacotados ao controle do código-fonte.

  8. Para concluir a atualização, aguarde a implantação.

  9. Verifique a atualização em seu ambiente de integração, preparo ou produção usando SSH para fazer logon e verificar a versão.

    code language-bash 
    php bin/magento --version

Atualizar extensões

Revise suas páginas de extensão e módulo de terceiros no Marketplace ou outros sites da empresa e verifique o suporte para o Adobe Commerce e o Adobe Commerce na infraestrutura em nuvem. Se for necessário atualizar extensões e módulos de terceiros, a Adobe recomenda trabalhar em uma nova ramificação de integração com as extensões desativadas.

Para verificar e atualizar suas extensões:

  1. Crie uma ramificação na estação de trabalho local.

  2. Desative as extensões conforme necessário.

  3. Quando disponível, baixar atualizações de extensão.

  4. Instale a atualização conforme documentado pela documentação de terceiros.

  5. Ative e teste a extensão.

  6. Adicione, confirme e envie as alterações de código para o remoto.

  7. Encaminhar e testar no ambiente de integração.

  8. Para testar um ambiente de pré-produção, envie para o ambiente de preparo.

A Adobe recomenda atualizar seu ambiente de Produção antes, incluindo as extensões atualizadas em seu processo de inicialização do site.

NOTE
Quando você atualiza a versão do seu aplicativo, o processo de atualização atualiza para a versão mais recente do módulo CDN Fastly automaticamente.

Solução de problemas de atualização

Se a atualização falhar, você receberá uma mensagem de erro no navegador indicando que não é possível acessar sua loja ou o painel Administrador:

There has been an error processing your request
Exception printing is disabled by default for security reasons.
  Error log record number: <error-number>

Para resolver o erro:

  1. Na estação de trabalho local, altere para o diretório do projeto.

  2. Use o SSH para fazer logon no ambiente remoto.

    code language-bash 
    magento-cloud ssh

  3. Abra o arquivo ./app/var/report/<error number>.

  4. Examine os logs e determine a origem do problema.

  5. Adicionar, confirmar e enviar alterações de código.

    code language-bash 
    git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>
recommendation-more-help
commerce-on-cloud-help-cloud-guide