文件Commerce雲端上的Commerce

升級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服務支援

若要在「測試」或「生產」中請求並完成Pro服務升級，請遵循下列步驟：

  1. 若要僅在Staging和Production環境中安裝或更新服務，請提交Adobe Commerce支援票證。

    在票證中，指定所需的服務變更，包括更新的.magento.app.yaml和.magento/services.yaml檔案，並記下目標PHP版本。

    PHP版本、Composer更新、擴充功能和環境設定是自助服務變更。 Adobe可能需要更新New Relic代理程式，以取得PHP版本的相容性。 檢視​ 應用程式組態 ​中的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支援或雲端基礎結構團隊的問題。
  • 確認​整合、擴充功能、自訂、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，請以Commerce的支援版本更新您的composer.json檔案。

    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才能將所有變更的檔案新增到原始檔控制中。 從基底封裝（magento/magento2-base和magento/magento2-ee-base）將composer install和composer update封送檔案合併到封裝根目錄中。

    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