文档Commerce云基础架构上的 Commerce 指南

配置Xdebug

Last update: Wed Nov 13 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在专业暂存和生产环境中已经可用。

配置完毕后，即可调试CLI命令、Web请求和代码。 请记住，所有云基础架构环境都是只读的。 将代码克隆到本地开发环境以执行调试。 对于Pro暂存环境和生产环境，请参阅有关Xdebug的其他说明。

要求

要运行和使用Xdebug，您需要环境的SSH URL。 您可以通过Cloud Console或您的Cloud Onboarding UI查找信息。

配置Xdebug

要配置Xdebug，请执行以下步骤：

分支入门

要添加Xdebug，Adobe建议在开发分支中工作。

在您的环境中启用Xdebug

您可以直接为所有入门环境和Pro集成环境启用Xdebug。 专业生产和暂存环境不需要此配置步骤。 请参阅Debug for Pro Staging and Production。

https://video.tv.adobe.com/v/3437407?learn=on

要为您的项目启用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 .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服务器

https://video.tv.adobe.com/v/3437409?learn=on

必须将PhpStorm IDE配置为正确使用Xdebug。

要将PhpStorm配置为使用Xdebug：

  1. 在PhpStorm项目中，打开​ 设置 ​面板。

    • macOS — 选择​ PhpStorm > 设置。
    • Windows/Linux — 选择​ 文件 > 设置。

  2. 在​ 设置 ​面板中，展开​ PHP ​部分并单击​ 服务器。

  3. 单击​ + ​以添加服务器配置。 项目名称在顶部为灰色。

  4. [可选]为新服务器配置以下设置。 请参阅​ PHPStorm ​文档中的未配置调试服务器。

    • 名称 — 输入与主机名相同的名称。 此值必须与Debug CLI命令中PHP_IDE_CONFIG变量的值匹配，才能使用CLI进行调试。
    • 主机 — 输入主机名。
    • 端口 — 输入443。
    • 调试器 — 选择Xdebug。

  5. 选择​ 使用路径映射。 在​ 文件/目录 ​窗格中，显示serverName的项目的根目录。

  6. 在服务器​ 上的 ​绝对路径列中，单击​ 编辑 ​图标并根据环境添加设置。

    • 对于所有Starter环境和Pro集成环境，远程路径为/app。

    • 对于Pro暂存和生产环境：

      • 生产： /app/<project_code>/
      • 暂存： /app/<project_code>_stg/

  7. 将Xdebug端口更改为9000,9003，或者可以在​ PHP > 调试 > Xdebug > 调试端口 ​面板中将其限制为仅9000。

  8. 单击​ 应用。

创建PHPStorm运行/调试配置

这使应用程序能够拥有正确的调试设置以处理来自Adobe Commerce应用程序的请求。

https://video.tv.adobe.com/v/3437426?learn=on

  1. 打开PHPStorm应用程序，然后单击屏幕右上角的​ Add Configuration。

  2. 单击​ Add new run configuration。

  3. 选择​ PHP Remote Debug ​选项。

    • 输入唯一但可识别的名称。
    • 选中Filter debug connection by IDE key**复选框。
    • 选择您在上一节中创建的服务器。 如果尚未创建，可以立即创建一个，但请参阅设置指南的这一部分。
    • 在​ IDE key(session id) ​文本字段中，输入大写字母中的PHPSTORM。 我们将在设置的其他部分使用此功能，因此保持不变非常重要。 如果选择其他字符串，则必须记得在设置和配置过程的其他位置使用它。

  4. 单击​ Apply > OK。

设置端口转发

https://video.tv.adobe.com/v/3437410?learn=on

将XDEBUG连接从服务器映射到本地系统。 要执行任何类型的调试，必须将端口9000从云基础架构服务器上的Adobe Commerce转发到本地计算机。 请参阅以下部分之一：

Mac或UNIX上的端口转发®

要在Mac或UNIX®环境中设置端口转发，请执行以下操作：

  1. 打开终端。

  2. 使用SSH建立连接。

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

    使用-v (verbose)选项，以便每当套接字连接到要转发的端口时，它都会显示在终端中。

    如果显示“无法连接”或“无法侦听远程端口”错误，则可能是另一个活动的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获取此信息。

  • 配置暂存和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 Console： https://CONSOLE-URL/ENVIRONMENT，单击SSH v下拉列表

要使用环境URL ​开始调试：

演示了用于启动远程GET会话的配置，以及调试参数。

https://video.tv.adobe.com/v/3437417?learn=on

  1. 启用远程调试；访问浏览器中的站点，并将以下内容附加到URL中，KEY为xdebug_key的值。

    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. 通过SSH连接到要使用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请求

以下步骤可帮助您调试Web请求。

  1. 在​ 扩展 ​菜单中，单击​ 调试 ​以启用。

  2. 右键单击，选择选项菜单，然后将IDE键设置为​ PHPSTORM。

  3. 在浏览器上安装Xdebug客户端。 配置并启用它。

示例：Chrome设置

本节讨论如何使用Xdebug帮助程序扩展在Chrome中使用Xdebug。 有关适用于其他浏览器的Xdebug工具的信息，请参阅浏览器文档。

要将Xdebug帮助程序与Chrome ​一起使用：

  1. 创建到云服务器的SSH通道。

  2. 从Chrome应用商店安装Xdebug Helper扩展。

  3. 在Chrome中启用该扩展，如下图所示。

    在Chrome中启用Xdebug扩展

  4. 在Chrome中，右键单击Chrome工具栏中的绿色帮助程序图标。

  5. 从弹出菜单中，单击​ 选项。

  6. 从​ IDE密钥 ​列表中，单击​ PhpStorm。

  7. 单击​ 保存。

    Xdebug帮助程序选项

  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