Atualizar versão do Commerce

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:

  • Serviços de atualização — como MariaDB (MySQL), OpenSearch, RabbitMQ e Redis — para compatibilidade com novas versões do Adobe Commerce.
  • Converta um arquivo de gerenciamento de configuração mais antigo.
  • 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.
  • Atualize o arquivo .gitignore.
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.
TIP
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 do live (Pro somente), você deve fornecer um aviso mínimo de 48 horas para permitir que a equipe de infraestrutura da nuvem tenha tempo suficiente para empacotar recursos e realizar uma atualização segura.

Atualizar a partir de versões anteriores

Se você estiver iniciando uma atualização de uma versão do Commerce anterior à versão 2.1, algumas restrições na base de código do Adobe Commerce poderão afetar sua capacidade de atualizar para uma versão específica das Ferramentas ECE ou de atualizar para a próxima versão do Commerce com suporte. Use a tabela a seguir para determinar o melhor caminho:

Versão atual
Caminho de atualização
2.1.3 e anterior
Atualize o Adobe Commerce para a versão 2.1.4 ou posterior antes de continuar. Em seguida, execute uma atualização única para instalar o ECE-Tools.
2.1.4 - 2.1.14
Atualizar pacote ECE-Tools.
Consulte as notas de versão de 2002.0.9 e versões posteriores de 2002.0.x.
2.1.15 - 2.1.16
Atualizar pacote ECE-Tools.
Consulte as notas de versão de2002.0.9 e posterior.
2.2.x e posterior
Atualizar pacote ECE-Tools.
Consulte as notas de versão de2002.0.8 e posterior.
NOTE
Se você usar uma versão do Adobe Commerce na infraestrutura em nuvem que não contenha o pacote ece-tools, será necessário executar uma atualização única para o projeto em nuvem, a fim de remover pacotes obsoletos. Se você usa atualmente o pacote ece-tools e precisa atualizá-lo, consulte Atualizar o pacote ECE-Tools.

Gerenciamento de configuração

Versões anteriores do Adobe Commerce, como 2.1.4 ou posterior a 2.2.x ou posterior, usavam um arquivo config.local.php para o Gerenciamento de configuração. O Adobe Commerce versão 2.2.0 e posterior usa o arquivo config.php, que funciona exatamente como o arquivo config.local.php, mas tem definições de configuração diferentes que incluem uma lista de módulos habilitados e opções de configuração adicionais.

Ao atualizar de uma versão mais antiga, você deve migrar o arquivo config.local.php para usar o arquivo config.php mais recente. Use as etapas a seguir para fazer backup do arquivo de configuração e criar um.

Para criar um config.php arquivo temporário:

  1. Crie uma cópia do arquivo config.local.php e nomeie-a como config.php.

  2. Adicione este arquivo à pasta app/etc do seu projeto.

  3. Adicione e confirme o arquivo na ramificação.

  4. Envie o arquivo para a ramificação de integração.

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

WARNING
Depois da atualização, você pode remover o arquivo config.php e gerar um arquivo novo e completo. Você só pode excluir este arquivo para substituí-lo desta vez. Após gerar um novo arquivo config.php completo, você não pode excluir o arquivo para gerar um novo. Consulte Gerenciamento de configuração e implantação de pipeline.

Verificar dependências do Zend Framework Composer

Ao atualizar de 2.2.x para 2.3.x ou posterior, verifique se as dependências do Zend Framework foram adicionadas à propriedade autoload do arquivo composer.json para dar suporte ao Laminas. Este plug-in suporta novos requisitos para o Zend Framework, que migrou para o projeto Laminas. Consulte Migration of Zend Framework to the Laminas Project no Magento DevBlog.

Para verificar a auto-load:psr-4 configuração:

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

  2. Confira a ramificação de integração.

  3. Abra o arquivo composer.json em um editor de texto.

  4. Verifique a seção autoload:psr-4 para a implementação do gerenciador de plug-in Zend para dependência de controladores.

    code language-json
     "autoload": {
        "psr-4": {
           "Magento\\Framework\\": "lib/internal/Magento/Framework/",
           "Magento\\Setup\\": "setup/src/Magento/Setup/",
           "Magento\\": "app/code/Magento/",
           "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
        },
    }
    
  5. Se a dependência Zend estiver ausente, atualize o arquivo composer.json:

    • Adicione a seguinte linha à seção autoload:psr-4.

      code language-json
      "Zend\\Mvc\\Controller\\": "setup/src/Zend/Mvc/Controller/"
      
    • Atualize as dependências do projeto.

      code language-bash
      composer update
      
    • Adicionar, confirmar e enviar alterações de código.

      code language-bash
      git add -A
      
      code language-bash
      git commit -m "Add Zend plugin manager implementation for controllers dependency for Laminas support"
      
      code language-bash
      git push origin <branch-name>
      
    • Mescle as alterações no ambiente de preparo e, em seguida, na produção.

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.

.magento.app.yaml

Sempre examine os valores contidos no arquivo .magento.app.yaml para a sua versão instalada, pois ele controla a maneira como o aplicativo é criado e implantado na infraestrutura de nuvem. O exemplo a seguir é para a versão 2.4.7 e usa o Composer 2.7.2. A propriedade build: flavor: não é usada para o Composer 2.x; consulte Instalando e usando o Composer 2.

Para atualizar o .magento.app.yaml arquivo:

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

  2. Abra e edite o arquivo magento.app.yaml.

  3. Atualize as opções do PHP.

    code language-yaml
    type: php:8.3
    
    build:
        flavor: none
    dependencies:
        php:
            composer/composer: '2.7.2'
    
  4. Modifique os comandos build e deploy da propriedade hooks.

    code language-yaml
    hooks:
        # We run build hooks before your application has been packaged.
        build: |
            set -e
            composer install
            php ./vendor/bin/ece-tools run scenario/build/generate.xml
            php ./vendor/bin/ece-tools run scenario/build/transfer.xml
        # We run deploy hook after your application has been deployed and started.
        deploy: |
            php ./vendor/bin/ece-tools run scenario/deploy.xml
        # We run post deploy hook to clean and warm the cache. Available with ECE-Tools 2002.0.10.
        post_deploy: |
            php ./vendor/bin/ece-tools run scenario/post-deploy.xml
    
  5. Adicione as variáveis de ambiente a seguir ao final do arquivo.

    Para o Adobe Commerce 2.2.x a 2.3.x-

    code language-yaml
    variables:
        env:
            CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com'
            CONFIG__STORES__DEFAULT__PAYMENT__BRAINTREE__CHANNEL: 'Magento_Enterprise_Cloud_BT'
            CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
    

    Para o Adobe Commerce 2.4.x-

    code language-yaml
    variables:
        env:
            CONFIG__DEFAULT__PAYPAL_ONBOARDING__MIDDLEMAN_DOMAIN: 'payment-broker.magento.com'
            CONFIG__STORES__DEFAULT__PAYPAL__NOTATION_CODE: 'Magento_Enterprise_Cloud'
    
  6. Salve o arquivo. Não confirme ou envie alterações para o ambiente remoto ainda.

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

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 versão de atualização usando a sintaxe de restrição de versão.

    code language-bash
    composer require "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 o projeto.

    code language-bash
    composer update
    
  4. 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.

  5. Aguarde a conclusão da implantação.

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

Criar um arquivo config.php

Como mencionado em Gerenciamento de configuração, após a atualização, você deve criar um arquivo config.php atualizado. Conclua todas as alterações adicionais de configuração por meio do Administrador no ambiente de integração.

Para criar um arquivo de configuração específico do sistema:

  1. No terminal, use um comando SSH para gerar o arquivo /app/etc/config.php para o ambiente.

    code language-bash
    ssh <SSH-URL> "<Command>"
    

    Por exemplo, para Pro, para executar o scd-dump na ramificação integration:

    code language-bash
    ssh <project-id-integration>@ssh.us.magentosite.cloud "php vendor/bin/ece-tools config:dump"
    
  2. Transfira o arquivo config.php para suas estações de trabalho locais usando rsync ou scp. Você só pode adicionar este arquivo à ramificação localmente.

    code language-bash
    rsync <SSH-URL>:app/etc/config.php ./app/etc/config.php
    
  3. Adicionar, confirmar e enviar alterações de código.

    code language-bash
    git add app/etc/config.php && git commit -m "Add system-specific configuration" && git push origin master
    

    Isso gera um arquivo /app/etc/config.php atualizado com uma lista de módulos e definições de configuração.

WARNING
Para uma atualização, você exclui o arquivo config.php. Depois que este arquivo for adicionado ao seu código, você deve não excluí-lo. Se precisar remover ou editar configurações, edite o arquivo manualmente.

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>
    
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26