文件Commerce雲端型 Commerce 的指南

[僅限PaaS]{class="badge informative" title="僅適用於雲端專案(Adobe管理的PaaS基礎結構)和內部部署專案的Adobe Commerce 。"}

雲端CLI

Last update: Fri Sep 12 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

  • 管理員
  • 開發人員

magento-cloud CLI是命令列工具，可讓開發人員和系統管理員從本機工作站管理雲端基礎結構專案和環境上的Adobe Commerce。

此工具提供額外的自動化功能，以及專案管理功能的直接存取，以擴充Cloud Console的功能。 在本機安裝工具後，您可以使用它來管理Starter和Pro整合環境。

NOTE
這是本機工具，僅支援Unix作業系統。 不支援Windows。 無法使用此頁面所述的方法將其安裝在雲端環境（唯讀）上。 您只能透過下列​ 部署工作流程 ​之一在雲端環境中安裝模組。

若要安裝magento-cloud CLI：

  1. 在您的​ 本機工作站 ​上，變更至您要複製雲端專案的目錄，且檔案系統擁有者具有​ 寫入 ​存取權。

  2. 安裝magento-cloud CLI。

    code language-bash 
    curl -sS https://accounts.magento.cloud/cli/installer | php

  3. 將magento-cloud CLI新增至Bash設定檔。

    code language-bash 
    export PATH=$PATH:$HOME/.magento-cloud/bin

  4. 重新載入更新的bash設定檔。

    code language-bash 
    . ~/.bash_profile

  5. 若要起始CLI，請呼叫magento-cloud，並在系統提示時輸入您的Cloud帳戶認證。

    code language-bash 
    magento-cloud
    code language-none 
    Welcome to Magento Cloud!
Please log in using your Magento Cloud account.
Your email address or username:

  6. 確認magento-cloud命令位於您的路徑中。 下列範例列出可用的命令。

    code language-bash 
    magento-cloud list

常用命令

Adobe設計這些命令來管理雲端整合環境，並建議您從專案目錄執行magento-cloud CLI，以便省略-p <project-ID>引數。

下列常用的magento-cloud CLI命令清單僅包含必要的選項。 您可以搭配任何命令使用--help選項來檢視詳細資訊。

命令
說明
magento-cloud login
登入專案。
magento-cloud list
列出CLI工具的可用指令。
magento-cloud environment:list
列出目前專案中的環境。
magento-cloud environment:checkout
檢視現有環境。
magento-cloud environment:merge -e
將此環境中的變更與其父項合併。
magento-cloud variables
此環境中的清單變數。
magento-cloud ssh
使用SSH連線到遠端環境。
magento-cloud url
在瀏覽器中開啟Adobe Commerce店面。
magento-cloud web
開啟Cloud Console。

環境命令

環境​ 名稱 ​與環境​ ID ​不同，前提是在環境名稱中使用空格或大寫字母。 環境ID包含所有小寫字母、數字和允許的符號。 環境名稱中的大寫字母會在ID中轉換為小寫；環境名稱中的空格會轉換為破折號。

環境名稱​ 不能 ​包含保留給Linux shell或規則運算式的字元。 禁止使用的字元包括大括弧({ })、括弧、星號(*)、角括弧(< >)、&符號(&)、% (%)及其他字元。

magento-cloud environment:list命令顯示環境階層，而git branch則不顯示。 如果您有任何巢狀環境，請使用下列專案：

magento-cloud environment:list

重新部署環境

不使用推播觸發重新部署。 驗證並確認要重新部署的環境。 如果有處於擱置狀態的組建，請勿使用重新部署。

magento-cloud environment:redeploy

範例回應：

Are you sure you want to redeploy the environment <environment-name>? [Y/n]
WARNING
當您執行環境的合併、推播或同步處理時，或當您觸發手動重新部署時（期間的Commerce應用程式處於維護模式），部署程式即會開始。 在生產環境中，Adobe建議您在離峰時間完成這項工作，以避免服務中斷。

Git命令

您可能會注意到其中有些指令類似於Git指令。 magento-cloud命令會直接連線至具有其他功能的Git型Cloud專案。 如果您未使用magento-cloud CLI建立分支，則不會「啟動」，而且當您推送變更至遠端環境時，也不會自動建置。 magento-cloud CLI命令包含啟用。

若要建立分支，請使用magento-cloud命令，讓分支啟動。

magento-cloud environment:branch <new-name> <parent-branch>

針對分支狀態：

  • 使用magento-cloud env命令檢視環境分支的清單及其狀態：作用中或非作用中。
  • 使用magento-cloud environment:activate命令啟動環境分支。

推送空的Git認可以觸發部署。 例如：

git commit --allow-empty -m "redeploy" && git push <branch-name>

有些動作（例如新增使用者）不會進行部署。

建立環境分支

下列步驟會示範如何交替使用CLI和Git指令來管理您的本機環境：

  1. 在本機工作站上，變更至專案目錄。

  2. 切換至檔案系統擁有者。

  3. 登入您的專案。

    code language-bash 
    magento-cloud login

  4. 列出您的專案。

    code language-bash 
    magento-cloud project:list

  5. 列出專案中的環境。 每個環境都包含一個作用中的Git分支，其中包含您的程式碼、資料庫、環境變數、設定和服務。

    code language-bash 
    magento-cloud environment:list
    note note
    NOTE
    使用magento-cloud environment:list命令很重要，因為它顯示環境階層，而git branch命令不顯示。

  6. 擷取來源分支以取得最新的程式碼。

    code language-bash 
    git fetch origin

  7. 簽出或切換至特定分支和環境。

    code language-bash 
    magento-cloud environment:checkout <environment-ID>

    Git命令只會檢查Git分支。 magento-cloud checkout命令會簽出分支並切換到使用中環境。

    note tip
    TIP
    您可以使用magento-cloud environment:branch <environment-name> <parent-environment-ID>命令語法來建立環境分支。 建立及啟用環境分支可能需要一些額外的時間。

  8. 使用環境ID將任何更新的程式碼提取到您的本機。 如果環境分支是新的，則不需要這樣做。

    code language-bash 
    git pull origin <environment-ID>

  9. （選擇性）建立環境的快照作為備份。

    code language-bash 
    magento-cloud snapshot:create -e <environment-ID>

更新CLI

magento-cloud CLI會在您登入時檢查可用的更新，但您可以使用self:update命令來檢查更新。 如果有可用的更新，請依照指示更新CLI。

如果您的magento-cloud CLI是最新的，您會看到下列回應：

magento-cloud update

Checking for Magento Cloud CLI updates (current version: X.XX.X)
No updates found
recommendation-more-help
7c2b03ac-000c-497d-aba3-2c6dc720a938