文件Commerce雲端基礎結構上的 Commerce 指南

設定Xdebug

Last update: Thu Sep 19 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

建立對象：

  • 管理員
  • 開發人員

Xdebug是用於偵錯PHP的擴充功能。 雖然您可以使用您選擇的IDE，以下說明如何設定Xdebug和PhpStorm以在本機環境中除錯。

NOTE
您可以設定Xdebug在Cloud Docker環境中執行以進行本機偵錯，而不變更雲端基礎結構專案設定上的Adobe Commerce。 請參閱為Docker設定Xdebug。

若要啟用Xdebug，您必須在Git存放庫中設定檔案、設定IDE，並設定連線埠轉送。 您可以在magento.app.yaml檔案中設定一些設定。 編輯之後，跨所有入門環境和Pro整合環境推送Git變更以啟用Xdebug。 Xdebug已在Pro測試和生產環境中可用。

設定之後，您就可以偵錯CLI命令、Web請求和程式碼。 請記住，所有雲端基礎結構環境都是唯讀的。 將程式碼複製到本機開發環境以執行偵錯。 若為Pro測試和生產環境，請參閱Xdebug的其他指示。

需求

若要執行並使用Xdebug，您需要環境的SSH URL。 您可以透過Cloud Console或您的Cloud Onboarding UI尋找資訊。

設定Xdebug

若要設定Xdebug，請遵循下列步驟：

開始使用分支

若要新增Xdebug，Adobe建議使用開發分支。

在您的環境中啟用Xdebug

您可以將Xdebug直接啟用至所有入門環境和Pro整合環境。 Pro生產和中繼環境不需要此設定步驟。 請參閱Pro Staging和生產的Debug。

若要啟用專案的Xdebug，請新增xdebug至.magento.app.yaml檔案的runtime:extensions區段。

若要啟用Xdebug：

  1. 在本機終端機中，以文字編輯器開啟.magento.app.yaml檔案。

  2. 在runtime區段的extensions下，新增xdebug。 例如：

    code language-yaml 
    runtime:
    extensions:
        - redis
        - xsl
        - newrelic
        - sodium
        - xdebug

  3. 儲存您對.magento.app.yaml檔案所做的變更，並結束文字編輯器。

  4. 新增、提交和推送變更以重新部署環境。

    code language-bash 
    git add -A
    code language-bash 
    git commit -m "Add xdebug"
    code language-bash 
    git push origin <environment-ID>

部署至入門環境和Pro整合環境時，Xdebug現在可供使用。 繼續設定IDE。 若為PhpStorm，請參閱設定PhpStorm。

設定PhpStorm

PhpStorm IDE必須設定為可正確搭配Xdebug使用。

若要設定PhpStorm以搭配Xdebug使用：

  1. 在您的PhpStorm專案中，開啟​ 設定 ​面板。

    • macOS — 選取​ PhpStorm > 偏好設定。
    • Windows/Linux — 選取​ 檔案 > 設定。

  2. 在​ 設定 ​面板中，展開並找到​ 語言與架構 > PHP > 伺服器 ​區段。

  3. 按一下​ + ​以新增伺服器組態。 專案名稱在頂端為灰色。

  4. [選擇性]為新伺服器組態設定下列設定。 請參閱​ PHPStorm ​檔案中的未設定偵錯伺服器。

    • 名稱 — 輸入與主機名稱相同的名稱。 此值必須符合偵錯CLI命令中PHP_IDE_CONFIG變數的值，才能使用CLI進行偵錯。
    • 主機 — 輸入主機名稱。
    • 連線埠 — 輸入443。
    • 偵錯工具 — 選取Xdebug。

  5. 選取​ 使用路徑對應。 在​ 檔案/目錄 ​窗格中，會顯示serverName的專案根目錄。

  6. 在伺服器​ 欄的 ​絕對路徑中，按一下​ 編輯 ​圖示，並根據環境新增設定。

    • 對於所有入門環境和Pro整合環境，遠端路徑為/app。

    • 對於Pro測試和生產環境：

      • 生產： /app/<project_code>/
      • 正在暫存： /app/<project_code>_stg/

  7. 在​ 語言與架構 > PHP > 偵錯 > Xdebug > 偵錯連線埠 ​面板中，將Xdebug連線埠變更為9000。

  8. 按一下​ 套用。

設定連線埠轉送

將伺服器的XDEBUG連線對應到您的本機系統。 若要執行任何型別的偵錯，您必須將連線埠9000從雲端基礎結構伺服器上的Adobe Commerce轉送至本機電腦。 請參閱下列其中一節：

Mac或UNIX上的連線埠轉送®

若要在Mac或UNIX®環境中設定連線埠轉送：

  1. 開啟終端機。

  2. 使用SSH建立連線。

    code language-bash 
    ssh -R 9000:localhost:9000 <ssh url>

    使用-v （詳細資訊）選項，以便每當通訊端連線到轉送的連線埠時，它就會顯示在終端機中。

    如果顯示「無法連線」或「無法接聽遠端連線埠」錯誤，則伺服器上可能持續存在另一個使用中的SSH工作階段，而此工作階段佔用連線埠9000。 如果該連線未使用，您可以終止它。

若要疑難排解連線：

  1. 使用SSH登入遠端整合、預備或生產環境。

  2. 檢視SSH工作階段清單： who

  3. 依使用者檢視現有的SSH工作階段。 請留意勿影響您以外的使用者！

    • 整合：使用者名稱類似於dd2q5ct7mhgus
    • 正在暫存：使用者名稱類似於dd2q5ct7mhgus_stg
    • 生產：使用者名稱類似於dd2q5ct7mhgus

  4. 對於比您更早的使用者工作階段，請尋找虛擬終端機(PTS)值，例如pts/0。

  5. 終止與PTS值對應的處理序ID (PID)。

    code language-bash 
    ps aux | grep ssh
kill <PID>

    範例回應：

    code language-none 
    dd2q5ct7mhgus        5504  0.0  0.0  82612  3664 ?      S    18:45   0:00 sshd: dd2q5ct7mhgus@pts/0

    若要終止連線，請輸入包含處理序ID (PID)的kill命令。

    code language-bash 
    kill 3664

Windows上的連線埠轉送

若要在Windows上設定連線埠轉送（SSH通道），您必須設定Windows終端機應用程式。 此範例會逐步使用Putty建立SSH通道。 您可以使用Cygwin等其他應用程式。 如需其他應用程式的詳細資訊，請參閱隨這些應用程式提供的廠商檔案。

若要使用Putty在Windows上設定SSH通道：

  1. 如果您尚未這樣做，請下載Putty。

  2. 啟動Putty。

  3. 在[類別]窗格中，按一下[工作階段]。

  4. 輸入下列資訊：

    • 主機名稱（或IP位址） ​欄位：輸入雲端伺服器的SSH URL
    • 連線埠 ​欄位：輸入22

    設定Putty

  5. 在​ 類別 ​窗格中，按一下​ 連線 > SSH > 通道。

  6. 輸入下列資訊：

    • Source連線埠 ​欄位：輸入9000
    • 目的地 ​欄位：輸入127.0.0.1:9000
    • 按一下​ 遠端

  7. 按一下​ 新增。

    在Putty中建立SSH通道

  8. 在​ 類別 ​窗格中，按一下​ 工作階段。

  9. 在​ 儲存的工作階段 ​欄位中，輸入此SSH通道的名稱。

  10. 按一下​ 儲存。

    儲存您的SSH通道

  11. 若要測試SSH通道，請按一下[載入]。​，然後按一下[開啟]。​

    如果顯示「無法連線」錯誤，請確認下列事項：

    • 所有Putty設定皆正確
    • 您正在雲端基礎結構上的私人Adobe Commerce SSH金鑰所在的電腦上執行Putty

透過SSH存取Xdebug環境

若要起始除錯、執行設定等作業，您需要SSH命令才能存取環境。 您可以透過Cloud Console和專案試算表取得此資訊。

對於入門環境和Pro整合環境，您可以使用以下magento-cloud CLI命令對這些環境執行SSH連結：

magento-cloud environment:ssh --pipe -e <environment-ID>

若要使用Xdebug，請依照下列方式使用SSH至環境：

ssh -R <xdebug listen port>:<host>:<xdebug listen port> <SSH-URL>

例如，

ssh -R 9000:localhost:9000 pwga8A0bhuk7o-mybranch@ssh.us.magentosite.cloud

針對Pro測試和生產進行除錯

NOTE
在Pro測試與生產環境中，Xdebug一律可用，因為這些環境對Xdebug有特殊設定。 所有一般Web要求都會路由到沒有Xdebug的專用PHP處理序。 因此，這些要求會正常處理，且載入Xdebug時不會發生效能降低的情況。 當傳送具有Xdebug金鑰的Web要求時，它會路由至已載入Xdebug的個別PHP處理序。

若要在Pro計畫測試和生產環境中使用Xdebug，您必須建立單獨的SSH通道和Web工作階段，只有您才有權存取。 此使用方法與一般存取不同，僅提供存取權給您，而非所有使用者。

您需要下列專案：

  • 用於存取環境的SSH命令。 您可以透過Cloud Console或您的Cloud Onboarding UI取得此資訊。

  • 設定Staging和Pro環境時所設定的xdebug_key值。

    可以使用SSH登入主要節點並執行：xdebug_key

    code language-bash 
    cat /etc/platform/*/nginx.conf | grep xdebug.sock | head -n1

若要設定SSH通道至測試或生產環境：

  1. 開啟終端機。

  2. 清除叢集之每個Web節點的所有SSH工作階段。

    code language-bash 
    ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'

  3. 為叢集的每個Web節點設定Xdebug的SSH通道。

    code language-bash 
    ssh -R /run/platform/USERNAME/xdebug.sock:localhost:9000 -N USERNAME@CLUSTER.ent.magento.cloud
NOTE
若要取得USERNAME@CLUSTER.ent.magento.cloud的正確值：
  • 方法1： magento-cloud CLI： magento-cloud ssh --all
  • 方法2： Commerce主控台： https://CONSOLE-URL/ENVIRONMENT，按一下SSH v下拉式清單

若要使用環境URL ​開始偵錯：

  1. 啟用遠端偵錯；造訪瀏覽器中的網站，並將下列專案附加至KEY為xdebug_key值的URL。

    code language-http 
    ?XDEBUG_SESSION_START=KEY

    此步驟會設定傳送瀏覽器請求以觸發Xdebug的Cookie。

  2. 使用Xdebug完成偵錯。

  3. 當您準備好結束工作階段時，請使用下列命令移除Cookie，並透過瀏覽器結束偵錯，其中KEY為xdebug_key的值。

    code language-http 
    ?XDEBUG_SESSION_STOP=KEY
    note note
    NOTE
    不支援POST要求所傳遞的XDEBUG_SESSION_START。

偵錯CLI命令

本節逐步解說如何偵錯CLI命令。

若要偵錯CLI命令：

  1. 使用CLI命令以連線方式連線至您要偵錯的伺服器。

  2. 建立下列環境變數：

    code language-bash 
    export XDEBUG_CONFIG='PHPSTORM'
    code language-bash 
    export PHP_IDE_CONFIG="serverName=<name of the server that is configured in PHPSTORM>"

    這些變數會在SSH工作階段結束時移除。

  3. 開始偵錯

    在入門環境和Pro整合環境中，執行CLI命令以進行偵錯。
    您可以新增執行階段選項，例如：

    code language-bash 
    php -d xdebug.profiler_enable=On -d xdebug.max_nesting_level=9999 bin/magento cache:clean

    在Pro測試環境和生產環境中，偵錯CLI命令時，您必須指定Xdebug PHP組態檔的路徑，例如：

    code language-bash 
    php -c /etc/platform/USERNAME/php.xdebug.ini bin/magento cache:clean

偵錯網頁請求

下列步驟可協助您偵錯Web請求。

  1. 在​ 擴充功能 ​功能表上，按一下​ 偵錯 ​以啟用。

  2. 按一下滑鼠右鍵，選取選項功能表，並將IDE金鑰設定為​ PHPSTORM。

  3. 在瀏覽器上安裝Xdebug使用者端。 設定並啟用它。

範例： Chrome設定

本節討論如何使用Xdebug Helper擴充功能在Chrome中使用Xdebug。 如需其他瀏覽器的Xdebug工具的相關資訊，請參閱瀏覽器檔案。

若要搭配Chrome ​使用Xdebug Helper：

  1. 建立SSH通道到雲端伺服器。

  2. 從Chrome市集安裝Xdebug Helper擴充功能。

  3. 在Chrome中啟用此擴充功能，如下圖所示。

    在Chrome中啟用Xdebug擴充功能

  4. 在Chrome中，以滑鼠右鍵按一下Chrome工具列中的綠色協助程式圖示。

  5. 從快顯功能表，按一下​ 選項。

  6. 從​ IDE索引鍵 ​清單中，按一下​ PhpStorm。

  7. 按一下​ 儲存。

    Xdebug Helper選項

  8. 開啟您的PhpStorm專案。

  9. 在頂端導覽列中，按一下​ 開始聆聽 ​圖示。

    如果未顯示導覽列，請按一下​ 檢視 > 導覽列。

  10. 在PhpStorm導覽窗格中，連按兩下PHP檔案以進行測試。

偵錯本機程式碼

由於是唯讀環境，您必須從環境或特定Git分支將程式碼提取至本機工作站，才能執行偵錯。

您選擇的方法由您決定。 您有以下選項：

  • 從Git簽出程式碼並執行composer install

    除非composer.json參考您無權存取的私人存放庫中的封裝，否則此方法有效。 此方法可取得整個Adobe Commerce程式碼基底。

  • 複製vendor、app、pub、lib和setup目錄

    此方法可讓您的程式碼完全可供測試。 視您擁有的靜態資產數量而定，可能會導致傳輸時間過長，並產生大量檔案。

  • 僅複製vendor目錄

    因為大部分的程式碼在vendor目錄中，所以此方法可能會產生良好的測試，雖然未測試整個程式碼基底。

若要壓縮檔案並將它們複製到本機電腦：

  1. 使用SSH登入遠端環境。

  2. 壓縮檔案。

    code language-bash 
    tar -czf /tmp/<file-name>.tgz <directory list>

    例如，只壓縮vendor目錄：

    code language-bash 
    tar -czf /tmp/vendor.tgz vendor

  3. 在您的本機環境中，使用PhpStorm來壓縮檔案。

    code language-bash 
    cd <phpstorm project root dir>
    code language-bash 
    rsync <SSH-URL>:/tmp/<file-name>.tgz .
    code language-bash 
    tar xzf <file-name>.tgz
recommendation-more-help
05f2f56e-ac5d-4931-8cdb-764e60e16f26