DocumentaçãoCommerceGuia do Commerce na nuvem

[Somente PaaS]{class="badge informative" title="Aplica-se somente a projetos do Adobe Commerce na nuvem (infraestrutura do PaaS gerenciada pela Adobe) e a projetos locais."}

Atualizar versão do Commerce

Last update: Tue Jul 15 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Criado para:

  • Administrador
  • Desenvolvedor

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

Dependendo da configuração do seu projeto, suas tarefas de atualização podem incluir o seguinte:

  • Atualize o arquivo .magento/services.yaml com novas versões para MariaDB (MySQL), OpenSearch, RabbitMQ e Redis para compatibilidade com novas versões do Adobe Commerce.
  • Atualize o arquivo .magento.app.yaml com novas configurações para ganchos e variáveis de ambiente.
  • Atualize extensões de terceiros para a versão mais recente com suporte.
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.
recommendation-more-help

  • Para projetos Pro, você deve enviar um tíquete de Suporte da Adobe Commerce para instalar ou atualizar os serviços somente em ambientes Staging e Production.

  • Indique as mudanças de serviço necessárias, inclua os arquivos atualizados do .magento.app.yaml e do services.yaml e informe a versão do PHP no tíquete. Para alterações de autoatendimento na versão, extensões ou configurações do ambiente do PHP, consulte configurações do PHP em Configuração do aplicativo.

  • Para alterações em um ambiente de Produção em tempo real (Somente profissionais), é necessário um aviso de no mínimo 48 horas. Isso permite que a equipe de infraestrutura da nuvem tenha tempo suficiente para empacotar recursos e realizar uma atualização segura. O período de aviso começa quando a equipe de infraestrutura reconhece a solicitação e programa a atualização, exceto nos finais de semana. Por exemplo, para que os upgrades de serviço sejam concluídos na segunda-feira, uma confirmação do upgrade agendado deve ser recebida até quarta-feira. Durante períodos de pico de demanda, pode levar mais tempo para processar sua solicitação.

style
shade-box

Arquivos de configuração

Antes de atualizar o aplicativo, você deve atualizar os arquivos de configuração do projeto para levar em conta as alterações nas configurações padrão do Adobe Commerce na infraestrutura em nuvem ou no 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 do projeto

Recomendamos criar um backup do seu projeto 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
    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
    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. Aguarde a conclusão da 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. Encaminhar para o ambiente de preparo para testar em um ambiente de pré-produção.

A Adobe recomenda que você atualize 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>
7c2b03ac-000c-497d-aba3-2c6dc720a938