文档CommerceCommerce on Cloud

升级Commerce版本

最近更新： 2026年9月1日

创建对象：

  • 管理员
  • 开发人员

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

根据环境类型（“开发”、“暂存”或“生产”），您的升级任务可能包括：

  • 将第三方扩展升级到支持的最新版本。

  • 使用MariaDB (MySQL)、OpenSearch、RabbitMQ以及Redis或Valkey所需的服务版本更新.magento/services.yaml文件，以便它们保持与目标Adobe Commerce版本兼容。

    • 对于开发/集成/PR分支，这些更改将直接用作环境配置的一部分。
    • 对于Pro暂存和生产环境，Adobe Commerce支持会执行实际的服务安装或更新，但您仍必须保持.magento/services.yaml最新、完整和有效，因为其内容在部署期间经过验证。

  • 使用挂接和环境变量的新设置更新.magento.app.yaml文件。

TIP
在开始升级或修补过程之前，请从集成环境创建一个活动分支，并将新分支签出到您的本地工作站。 将分支专用于升级或修补过程有助于避免干扰正在进行的工作。

专业服务支持

要在暂存或生产环境中请求并完成Pro服务升级，请执行以下步骤：

  1. 若要仅在Staging和Production环境中安装或更新服务，请提交Adobe Commerce支持票证。

    在票证中，指定所需的服务更改，包括更新的.magento.app.yaml和.magento/services.yaml文件，并记下目标PHP版本。

    PHP版本、编辑器更新、扩展和环境设置都是自助更改。 为兼容PHP版本，Adobe可能需要更新New Relic代理。 查看​ 应用程序配置 ​中的PHP设置。

    note important
    IMPORTANT
    在票证表单中选择​ Environment ​字段时，请使用Adobe的环境命名。 例如，即使您在内部调用该环境​Dev，请选择“暂存”。 您可以在描述中提及您的内部名称，但Environment字段必须使用Adobe的命名法。

  2. 通过Adobe的两部分流程确认升级计划：首先确认请求的日期和时间，然后支持部门将其提交给基础架构团队进行最终确认。

    生产变更（仅限Pro）需要提前至少两个工作日发出通知，不包括周末。 例如，Cloud Infrastructure团队必须在前一个星期三确认星期一的升级。 预计需求高峰期会有额外的提前期。 为避免延迟，请在窗口之前至少48小时响应初始请求。 在收到最终确认之前，不会将升级视为已计划。

    note
    NOTE
    提供UTC格式的维护时段。 暂存升级不会提前计划，通常与请求在同一天完成。
    RabbitMQ升级后，重新部署环境以重新初始化消息队列。

  3. 先在暂存或集成环境中验证升级，然后再在生产环境中计划升级。

    在服务升级后的重新部署期间，由第三方模块、自定义代码或依赖关系兼容性导致的问题通常会浮出水面。 要一次验证多个服务升级，合理的顺序依次为Valkey或Redis、RabbitMQ、OpenSearch和MariaDB。 这不是必需的序列。 数据库升级具有最高的操作影响，应引起最大的警觉。

    Adobe不保证提前生产维护窗口的确切持续时间，因为时间取决于环境和涉及的服务。 在规划“生产”窗口时，将暂存升级所花费的时间作为实际估计值。

  4. 在Adobe完成服务升级后​重新部署环境，以使更改生效，即使Adobe Commerce应用程序版本未更改也是如此。

    如果升级包括OpenSearch，则还应计划完全重新索引。 Adobe无法保证服务升级的零停机时间，因此请规划一个维护时段，以便有时间重新部署、根据需要重新编制索引，并在重新打开网站之前验证店面和管理员。

客户在升级期间的可用性

在计划的生产升级时段内，您的团队或实施合作伙伴的代表必须在线可用。 在低流量期间进行计划不会使升级自动进行。 Adobe管理云基础架构升级，但无法验证您的应用程序行为、集成、自定义代码或业务工作流。

可用的代表必须能够：

  • 监控​升级期间和升级后的店面交易和关键业务交易。
  • 回复 Adobe支持或Cloud Infrastructure团队提出的问题。
  • 确认​集成、扩展、自定义、cron作业、队列和其他特定于客户的功能均按预期工作。
  • 验证​业务关键型工作流，如签出、目录视图、搜索、登录和订单处理。
  • 当升级上下文和日志仍然可用时，立即​ 报告 ​意外行为。
TIP
对于Pro项目，生产中的服务升级还需要提前计划和包含Adobe支持的两部分确认流程。 请参阅专业服务支持。

维护模式

维护模式不能代替客户可用性。 维护模式会阻止店面访问，但不会验证应用程序服务、集成、队列、cron作业、结账或其他特定于客户的功能。

如果计划内的工作需要维护模式，请协调与Adobe支持人员一起使用它，然后按照该升级说明操作。 之后，在考虑工作完成之前，请确认店面工作流和关键工作流运行正常。

配置文件

要考虑对云基础架构或应用程序上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. 继续升级过程。

环境备份

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

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

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

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

  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
    您必须使用版本约束语法才能成功更新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文件中应用了任何[质量修补程序]，请验证它们是否仍可应用于新版本。 从.magento.env.yaml文件的QUALITY_PATCHES部分删除不适用的修补程序。

    方法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>
recommendation-more-help
commerce-on-cloud-help-cloud-guide