文件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，請以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，請確認它們是否仍可套用至新版本。 從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