文档Commerce云上 Commerce 指南

[仅限PaaS]{class="badge informative" title="仅适用于云项目(Adobe管理的PaaS基础架构)和内部部署项目上的Adobe Commerce 。"}

升级Commerce版本

Last update: Tue Jul 15 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：
  • 云

创建对象：

  • 管理员
  • 开发人员

您可以将Adobe Commerce代码库升级到较新版本。 在升级项目之前，请查看安装指南中的​ 系统要求 ​以了解最新的软件版本要求。

根据您的项目配置，升级任务可能包括以下内容：

  • 使用MariaDB (MySQL)、OpenSearch、RabbitMQ和Redis的新版本更新.magento/services.yaml文件，以便与新的Adobe Commerce版本兼容。
  • 使用挂接和环境变量的新设置更新.magento.app.yaml文件。
  • 将第三方扩展升级到支持的最新版本。
TIP
在开始升级或修补过程之前，请从集成环境创建一个活动分支，并将新分支签出到您的本地工作站。 将分支专用于升级或修补过程有助于避免干扰正在进行的工作。
recommendation-more-help

  • 对于Pro项目，您必须提交Adobe Commerce支持票证才能仅在和环境中安装或更新Staging服务Production。

  • 指示所需的服务更改，包括更新的.magento.app.yaml和services.yaml文件，并在票证中声明PHP版本。 有关对PHP版本、扩展或环境设置的自助更改，请参阅应用程序配置中的​ PHP设置。

  • 对实时生产环境的更改（仅限​ Pro），至少需要48小时的通知。 这使云基础架构团队有充足的时间来调配资源并进行安全升级。 当基础架构团队确认请求并计划升级（不包括周末）时，通知期即开始。 例如，要在星期一完成服务升级，必须在星期三之前收到计划升级的确认。 在需求高峰期，处理您的请求可能需要更多时间。

style
shade-box

配置文件

在升级应用程序之前，必须更新项目配置文件，以便考虑对云基础架构或应用程序上Adobe Commerce的默认配置设置所做的更改。 可以在magento-cloud GitHub存储库中找到最新的默认值。

composer.json

升级之前，请始终检查composer.json文件中的依赖项是否与Adobe Commerce版本兼容。

要更新Adobe Commerce版本2.4.4及更高版本的composer.json文件**：

  1. 将以下allow-plugins添加到config部分：

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

  2. 将以下插件添加到require部分：

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

  3. 将以下组件添加到extra:component_paths部分：

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

  4. 保存文件。 尚未提交更改或将更改推送到分支。

  5. 继续升级过程。

项目备份

我们建议在升级之前创建项目的备份。 使用以下步骤可备份集成、暂存和生产环境。

要备份集成环境数据库和代码：

  1. 创建远程数据库的本地备份。

    code language-bash 
    magento-cloud db:dump
    note note
    NOTE
    magento-cloud db:dump命令运行带有标志的mysqldump--single-transaction命令，该标志允许您在不锁定表的情况下备份数据库。

  2. 备份代码和介质。

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

    或者，如果您有大量静态文件已在源代码管理中，则可以省略[--media]。

要在部署 ​之前备份暂存或生产环境数据库，请执行以下操作：

  1. 使用SSH登录到远程环境。

  2. 创建数据库转储。 要为数据库转储选择目标目录，请使用--dump-directory选项。

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

    转储操作将在远程项目目录中创建dump-<timestamp>.sql.gz存档文件。 请参阅备份数据库。

应用程序升级

在升级应用程序之前，请查看服务版本信息以了解最新的软件版本要求。

升级应用程序版本：

  1. 在本地工作站上，转到您的项目目录。

  2. 为目标升级版本设置版本约束。 仅当目标版本位于现有约束之外时，才需要执行此步骤。

    code language-bash 
    composer require-commerce "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    note note
    NOTE
    您必须使用版本约束语法才能成功更新ece-tools包。 您可以在composer.json文件中找到用于升级的应用程序模板的版本限制。

  3. 使用核心Commerce升级版本更新您的composer.json文件。

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

  4. 如果您使用的是B2B，请将您的composer.json文件更新为Commerce的支持的版本。

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

  5. 更新项目依赖关系。

    code language-bash 
    composer update

  6. 查看当前应用的修补程序：

    • 如果m2-hotfixes目录中安装了任何修补程序，请提交Adobe Commerce支持票证，并与Adobe Commerce支持部门合作，验证哪些修补程序仍可以应用于新版本。 从m2-hotfixes目录中删除不适用的修补程序。

    • 如果[文件中应用了任何]质量修补程序.magento.env.yaml，请验证它们是否仍可应用于新版本。 从QUALITY_PATCHES文件的.magento.env.yaml部分删除不适用的修补程序。

    方法1： 验证Quality Patches发行说明中的适用版本

    方法2： 查看可用的修补程序和状态

    方法3： 搜索修补程序

  7. 添加、提交和推送代码更改。

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

    由于Composer封送基础包的方式，将所有更改的文件添加到源代码管理时需要git add -A。 composer install和composer update将基包（magento/magento2-base和magento/magento2-ee-base）中的文件封送到包根中。

    Composer封送的文件属于新版本的Adobe Commerce，用于覆盖这些相同文件的过时版本。 目前，Adobe Commerce中已禁用封送处理，因此您必须将封送处理文件添加到源代码管理。

  8. 等待部署完成。

  9. 通过使用SSH登录并检查版本，在集成、暂存或生产环境中验证升级。

    code language-bash 
    php bin/magento --version

升级扩展

在Marketplace或其他公司站点中查看您的第三方扩展和模块页面，并验证在云基础架构上对Adobe Commerce和Adobe Commerce的支持。 如果必须升级任何第三方扩展和模块，Adobe建议在禁用扩展的情况下使用新的集成分支。

验证并升级扩展：

  1. 在本地工作站上创建分支。

  2. 根据需要禁用扩展。

  3. 可用时，下载扩展升级。

  4. 按照第三方文档的说明安装升级。

  5. 启用并测试扩展。

  6. 添加、提交代码更改并将其推送到远程。

  7. 推送到并在您的集成环境中测试。

  8. 推送到暂存环境以在预生产环境中测试。

Adobe强烈建议在​ 之前升级您的生产环境，包括在您的站点启动过程中升级的扩展。

NOTE
当您升级应用程序版本时，升级过程将自动更新到Fastly CDN模块的最新版本。

升级疑难解答

如果升级失败，您会在浏览器中收到一条错误消息，指示您无法访问店面或管理面板：

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

要解决错误：

  1. 在本地工作站上，转到您的项目目录。

  2. 使用SSH登录到远程环境。

    code language-bash 
    magento-cloud ssh

  3. 打开./app/var/report/<error number>文件。

  4. 检查日志并确定问题的来源。

  5. 添加、提交和推送代码更改。

    code language-bash 
    git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>
7c2b03ac-000c-497d-aba3-2c6dc720a938