設定Xdebug
Xdebug是用於偵錯PHP的擴充功能。 雖然您可以使用您選擇的IDE,以下說明如何設定Xdebug和PhpStorm以在本機環境中除錯。
若要啟用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:
-
在本機終端機中,以文字編輯器開啟
.magento.app.yaml
檔案。 -
在
runtime
區段的extensions
下,新增xdebug
。 例如:code language-yaml runtime: extensions: - redis - xsl - newrelic - sodium - xdebug
-
儲存您對
.magento.app.yaml
檔案所做的變更,並結束文字編輯器。 -
新增、提交和推送變更以重新部署環境。
code language-bash git add .magento.app.yaml
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使用:
-
在您的PhpStorm專案中,開啟 設定 面板。
- macOS — 選取 PhpStorm > 設定。
- Windows/Linux — 選取 檔案 > 設定。
-
在 設定 面板中,展開 PHP 區段並按一下 伺服器。
-
按一下 + 以新增伺服器組態。 專案名稱在頂端為灰色。
-
[選擇性]為新伺服器組態設定下列設定。 請參閱 PHPStorm 檔案中的未設定偵錯伺服器。
- 名稱 — 輸入與主機名稱相同的名稱。 此值必須符合偵錯CLI命令中
PHP_IDE_CONFIG
變數的值,才能使用CLI進行偵錯。 - 主機 — 輸入主機名稱。
- 連線埠 — 輸入
443
。 - 偵錯工具 — 選取
Xdebug
。
- 名稱 — 輸入與主機名稱相同的名稱。 此值必須符合偵錯CLI命令中
-
選取 使用路徑對應。 在 檔案/目錄 窗格中,會顯示
serverName
的專案根目錄。 -
在伺服器 欄的 絕對路徑中,按一下 編輯 圖示,並根據環境新增設定。
-
對於所有入門環境和Pro整合環境,遠端路徑為
/app
。 -
對於Pro測試和生產環境:
- 生產:
/app/<project_code>/
- 正在暫存:
/app/<project_code>_stg/
- 生產:
-
-
將Xdebug連線埠變更為
9000,9003
,或者您可以在 PHP > 偵錯 > Xdebug > 偵錯連線埠 面板中將其限製為只有9000
。 -
按一下 套用。
建立PHPStorm執行/偵錯組態
這可讓應用程式擁有正確的偵錯設定,以處理來自Adobe Commerce應用程式的請求。
-
開啟PHPStorm應用程式,然後按一下畫面右上角的 Add Configuration。
-
按一下 Add new run configuration。
-
選取 PHP Remote Debug 選項。
- 輸入唯一但可辨識的名稱。
- 勾選「Filter debug connection by IDE key**」核取方塊。
- 選取您在上一節中建立的伺服器。 如果您尚未建立,可以現在建立,但請參閱設定指南的該部分。
- 在 IDE key(session id) 文字欄位中,以大寫字母輸入
PHPSTORM
。 我們會在設定的其他部分使用此專案,因此請務必維持不變。 如果您選擇其他字串,則必須記得在設定和組態程式的其他位置使用它。
-
按一下 Apply > OK。
設定連線埠轉送
將伺服器的XDEBUG
連線對應到您的本機系統。 若要執行任何型別的偵錯,您必須將連線埠9000從雲端基礎結構伺服器上的Adobe Commerce轉送至本機電腦。 請參閱下列其中一節:
Mac或UNIX上的連線埠轉送®
若要在Mac或UNIX®環境中設定連線埠轉送:
-
開啟終端機。
-
使用SSH建立連線。
code language-bash ssh -R 9000:localhost:9000 <ssh url>
使用
-v
(詳細資訊)選項,以便每當通訊端連線到轉送的連線埠時,它就會顯示在終端機中。如果顯示「無法連線」或「無法接聽遠端連線埠」錯誤,則伺服器上可能持續存在另一個使用中的SSH工作階段,而此工作階段佔用連線埠9000。 如果該連線未使用,您可以終止它。
若要疑難排解連線:
-
使用SSH登入遠端整合、預備或生產環境。
-
檢視SSH工作階段清單:
who
-
依使用者檢視現有的SSH工作階段。 請留意勿影響您以外的使用者!
- 整合:使用者名稱類似於
dd2q5ct7mhgus
- 正在暫存:使用者名稱類似於
dd2q5ct7mhgus_stg
- 生產:使用者名稱類似於
dd2q5ct7mhgus
- 整合:使用者名稱類似於
-
對於比您更早的使用者工作階段,請尋找虛擬終端機(PTS)值,例如
pts/0
。 -
終止與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通道:
-
如果您尚未這樣做,請下載Putty。
-
啟動Putty。
-
在[類別]窗格中,按一下[工作階段]。
-
輸入下列資訊:
- 主機名稱(或IP位址) 欄位:輸入雲端伺服器的SSH URL
- 連線埠 欄位:輸入
22
-
在 類別 窗格中,按一下 連線 > SSH > 通道。
-
輸入下列資訊:
- Source連線埠 欄位:輸入
9000
- 目的地 欄位:輸入
127.0.0.1:9000
- 按一下 遠端
- Source連線埠 欄位:輸入
-
按一下 新增。
-
在 類別 窗格中,按一下 工作階段。
-
在 儲存的工作階段 欄位中,輸入此SSH通道的名稱。
-
按一下 儲存。
-
若要測試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測試和生產進行除錯
若要在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通道至測試或生產環境:
-
開啟終端機。
-
清除叢集之每個Web節點的所有SSH工作階段。
code language-bash ssh USERNAME@CLUSTER.ent.magento.cloud 'rm /run/platform/USERNAME/xdebug.sock'
-
為叢集的每個Web節點設定Xdebug的SSH通道。
code language-bash ssh -R /run/platform/USERNAME/xdebug.sock:localhost:9000 -N USERNAME@CLUSTER.ent.magento.cloud
USERNAME@CLUSTER.ent.magento.cloud
的正確值:- 方法1: magento-cloud CLI:
magento-cloud ssh --all
- 方法2: Commerce主控台: https://CONSOLE-URL/ENVIRONMENT,按一下
SSH v
下拉式清單
若要使用環境URL 開始偵錯:
這是用來啟動遠端偵錯工作階段之設定的示範,以及啟動遠端偵錯工作階段的GET引數的示範。
-
啟用遠端偵錯;造訪瀏覽器中的網站,並將下列專案附加至
KEY
為xdebug_key
值的URL。code language-http ?XDEBUG_SESSION_START=KEY
此步驟會設定傳送瀏覽器請求以觸發Xdebug的Cookie。
-
使用Xdebug完成偵錯。
-
當您準備好結束工作階段時,請使用下列命令移除Cookie,並透過瀏覽器結束偵錯,其中
KEY
為xdebug_key
的值。code language-http ?XDEBUG_SESSION_STOP=KEY
note note NOTE 不支援 POST
要求所傳遞的XDEBUG_SESSION_START
。
偵錯CLI命令
本節逐步解說如何偵錯CLI命令。
若要偵錯CLI命令:
-
使用CLI命令以連線方式連線至您要偵錯的伺服器。
-
建立下列環境變數:
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工作階段結束時移除。
-
開始偵錯
在入門環境和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請求。
-
在 擴充功能 功能表上,按一下 偵錯 以啟用。
-
按一下滑鼠右鍵,選取選項功能表,並將IDE金鑰設定為 PHPSTORM。
-
在瀏覽器上安裝Xdebug使用者端。 設定並啟用它。
範例: Chrome設定
本節討論如何使用Xdebug Helper擴充功能在Chrome中使用Xdebug。 如需其他瀏覽器的Xdebug工具的相關資訊,請參閱瀏覽器檔案。
若要搭配Chrome 使用Xdebug Helper:
-
建立SSH通道到雲端伺服器。
-
從Chrome市集安裝Xdebug Helper擴充功能。
-
在Chrome中啟用此擴充功能,如下圖所示。
-
在Chrome中,以滑鼠右鍵按一下Chrome工具列中的綠色協助程式圖示。
-
從快顯功能表,按一下 選項。
-
從 IDE索引鍵 清單中,按一下 PhpStorm。
-
按一下 儲存。
-
開啟您的PhpStorm專案。
-
在頂端導覽列中,按一下 開始聆聽 圖示。
如果未顯示導覽列,請按一下 檢視 > 導覽列。
-
在PhpStorm導覽窗格中,連按兩下PHP檔案以進行測試。
偵錯本機程式碼
由於是唯讀環境,您必須從環境或特定Git分支將程式碼提取至本機工作站,才能執行偵錯。
您選擇的方法由您決定。 您有以下選項:
-
從Git簽出程式碼並執行
composer install
除非
composer.json
參考您無權存取的私人存放庫中的封裝,否則此方法有效。 此方法可取得整個Adobe Commerce程式碼基底。 -
複製
vendor
、app
、pub
、lib
和setup
目錄此方法可讓您的程式碼完全可供測試。 視您擁有的靜態資產數量而定,可能會導致傳輸時間過長,並產生大量檔案。
-
僅複製
vendor
目錄因為大部分的程式碼在
vendor
目錄中,所以此方法可能會產生良好的測試,雖然未測試整個程式碼基底。
若要壓縮檔案並將它們複製到本機電腦:
-
使用SSH登入遠端環境。
-
壓縮檔案。
code language-bash tar -czf /tmp/<file-name>.tgz <directory list>
例如,只壓縮
vendor
目錄:code language-bash tar -czf /tmp/vendor.tgz vendor
-
在您的本機環境中,使用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