解决常见的 PHP 调试问题

收集 PhpStorm 调试日志

如果本节未解决您的问题，请联系我们的支持工程师。如果要求提供部署日志，请按照说明收集它们。

收集 Xdebug 日志

使用 Xdebug 时，可以使其记录其操作。

1. 在设置/首选项对话框 ( Ctrl+Alt+S) 中，转到PHP。

2. 从PHP 可执行文件列表中，选择相关的 PHP 解释器并单击它旁边的。在打开的CLI 解释器对话框中，单击配置文件旁边的在编辑器中打开链接：<path to php.ini>文件。关闭所有对话框并切换到打开php.ini文件的选项卡。

3. 在php.ini中，通过添加以下行来启用 Xdebug 日志记录：

   xdebug.log="path_to_log/xdebug.log"

   xdebug.remote_log="path_to_log/xdebug.log"

   日志文件包含 PhpStorm 和 Xdebug 之间的原始通信以及任何警告或错误：

   日志于 2018-01-08 08:14:28 打开 I：连接到配置的地址/端口：127.0.0.1:9000。I：连接到客户端。:-) -> <init xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" fileuri="file:///C:/Projects/Samples/DebuggingTutorial/debugging. php" language="PHP" protocol_version="1.0" appid="3040" idekey="11774"><engine version="2.2.5"><![CDATA[Xdebug]]></engine><author>< ![CDATA[Derick Rethans]]></author><url><![CDATA[https://xdebug.org]]></url><copyright><![CDATA[Copyright (c) 2002-2018德里克·雷森斯 (Derick Rethans)]]></copyright>

确保安装和配置了 Xdebug 或 Zend Debugger

要使用 PhpStorm 调试 PHP 代码，请确保您已正确安装和配置了调试引擎Xdebug或Zend Debugger 。

这些工具不能同时使用，因为它们相互阻挡。为避免此问题，您需要更新php.ini文件中的相应部分，如配置 Xdebug和配置 Zend Debugger中所述。

要验证调试引擎配置，请执行验证调试引擎配置中描述的步骤

阻止调试器工作的启动警告和错误

运行 PHP 时，可能会显示启动警告或错误。在这种情况下，调试器可能无法工作。PhpStorm 也将无法识别正在使用的调试器。

要验证没有显示启动警告或错误，请运行以下命令：

这将返回类似于以下内容的消息：

如果第一行出现任何错误或警告，建议在继续之前修复它们。

调试器无法连接

当调试器无法连接或拒绝连接时，请检查以下内容：

• 确保 Xdebug 或 Zend Debugger 配置为连接到主机和端口 PhpStorm 正在运行。

  • 在 Xdebug 配置中，确保xdebug.remote_host和xdebug.remote_port（对于 Xdebug 3）是正确的。有关详细信息，请参阅Xdebug 文档。xdebug.client_hostxdebug.client_port

  • 使用 Zend 调试器时，确保生成的PhpStorm 小书签或浏览器调试扩展配置为使用正确的 IP 地址和端口。

  • 使用远程 PHP 解释器时，请验证通过 SSH 隧道进行远程调试中概述的步骤。

• 在设置/首选项对话框 ( Ctrl+Alt+S) 中，导航到PHP | 调试并确保 PhpStorm 和 Xdebug / Zend Debugger 配置了相同的端口号。

• 在 PhpStorm 中，通过单击工具栏或选择Run |启用侦听传入调试连接。在主菜单中开始侦听 PHP 调试连接。这将确保 PhpStorm 在启动调试会话时做出反应并自动打开调试工具窗口。在启动脚本之前，请确保设置了断点，或者在Settings/Preferences对话框的Debug页面上启用了Break at first line in PHP scripts选项。Ctrl+Alt+S

• 确认没有防火墙、路由器或 ISP 阻止连接。这可以通过从远程服务器（其中主机是运行 PhpStorm 的本地机器的 IP 地址）运行telnet host 9000 (for Xdebug)或telnet host 10137（对于 Zend 调试器）并检查连接是否建立来验证。您可以使用http://www.canyouseeme.org或类似的服务来检查打开的入站端口。

• 确保正确配置了xdebug.remote_host（对于 Xdebug 2）、xdebug.client_host（对于 Xdebug 3）或zend_debugger .allow_hosts（对于 Zend Debugger）。该值可以是主机名（例如localhost）或运行 PhpStorm 的机器的 IP 地址，并且它必须可以从服务器 ping 通。使用 Xdebug 时，可以使用xdebug.remote_connect_back（对于 Xdebug 2）或xdebug.discover_client_host（对于 Xdebug 3）进行故障排除。

未配置调试服务器

如果您在没有配置调试服务器的情况下启动零配置调试会话，则在建立连接时 PhpStorm 会显示传入连接对话框，其中建议从服务器访问配置（部署配置）导入映射。如果选择Import mappings from deployment，PhpStorm 会尝试检测最合适的部署配置，在Deployment列表中预先选择它，并且Preview 区域显示项目文件的绝对路径，该路径根据来自的映射对应当前执行的脚本选择的配置。

如果 PhpStorm 未检测到相关配置：

1. 从列表中选择最合适的配置或单击并在打开的部署对话框中创建新配置，然后将新配置添加到列表中。

2. 在部署根字段中，输入服务器根文件夹的绝对路径。

您还可以选择手动选择本地文件或项目选项，在这种情况下，PhpStorm 显示项目树视图，您可以在其中选择项目文件并将当前执行的脚本映射到它。您还可以选择和映射整个项目。

要继续使用导入的或手动指定的配置设置进行调试，请单击接受。

远程文件路径未映射到项目中的任何文件路径

在某些情况下，调试器可以连接，但您会收到错误消息，表明没有定义远程文件和项目文件之间的映射。这意味着 PhpStorm 无法确定哪个本地文件对应于正在调试的文件。

要解决此问题，请单击单击设置路径映射并提供必要的路径映射。

当服务器处理的文件的路径与 PhpStorm 项目中文件的路径不同时，使用路径映射。这发生在以下情况：

• 服务器是远程的，项目文件是原件的本地副本。

• 服务端处理的文件和IDE打开的文件是一样的，只是使用了符号链接。因为调试器在调试会话期间解析符号链接，所以您需要告诉 IDE 到服务器上文件的实际溶质物理路径。

要配置路径映射，在设置/首选项对话框 ( Ctrl+Alt+S) 中，导航到PHP | 服务器。

如果服务器处理的文件在项目中并且您没有使用符号链接，请清除使用路径映射复选框。在这种情况下，IDE 将根据从调试器接收到的路径打开文件。

为父目录指定的路径映射会自动应用于其所有子目录。如有必要，可以指定任何子目录或文件的路径映射。

有关详细信息，请参阅配置与 Web 服务器的同步。

没有命中断点

当断点未命中但调试器似乎已连接时，请验证以下内容：

• 验证断点未被禁用。使用运行 | 查看断点菜单命令Ctrl+Shift+F8，检查断点是否启用。选中断点旁边的复选框以启用它。

• 确保路径映射正确。

• 在 macOS 上，当使用 Finder 重命名文件或文件夹并更改字母大小写时，PhpStorm 可能无法找到文件。如果需要重命名，请确保在 IDE 中或使用终端和mv命令进行。使用 Finder 重命名项目文件或文件夹可能会导致奇怪的行为。有关更多详细信息，请参见此处。

• 在极少数情况下，由于技术限制无法命中断点，例如 PHP 生成字节码的方式造成的。有关更多详细信息，请参见此处。

使用 Xdebug 时，您可以使用该xdebug_break()函数在 PHP 中强制设置断点。当 Xdebug 在执行过程中遇到这个函数时，它会在 IDE 中的下一条语句处暂停，即使原来这里没有定义断点。

Xdebug 忽略断点并停在没有定义断点的行

这可能是由于 Xdebug 的内部断点解析机制而发生的。在这种机制下，调试器评估 PHP 是否可以为当前行生成内部可执行字节码。如果没有为一行生成这样的代码，则无法命中相应的断点。Xdebug 将扫描最多 5 个后续行，并在可执行代码所在的行停止。Xdebug 2.8 及更高版本支持解析断点。

如有必要，您可以在PHP |上的 PhpStorm 中配置断点解析支持。设置/首选项对话框的调试页面( Ctrl+Alt+S)：

• 在Xdebug区域中，使用Resolve breakpoint if it is not available on the current line (Xdebug 2.8+)复选框来切换断点解析。请注意，如果禁用解析，则在没有可执行代码的代码行上设置的断点将始终被忽略。

• 在Advanced settings区域中，使用Notify if breakpoint was resolved to a different line (Xdebug 2.8+)复选框来选择 PhpStorm 是否应该在断点被解析时显示通知消息。

脚本未挂起

建立零配置调试会话可能会失败，没有命中断点，因此脚本不会挂起。如果路径映射未配置或配置错误，或者您未设置任何断点，则可能会发生这种情况。在后一种情况下，您可以执行以下任何操作：

• 通过单击所需可执行代码行处的装订线来设置断点。有关详细信息，请参阅断点。

• 在设置/首选项对话框 ( Ctrl+Alt+S) 中，转到PHP | 调试并在External Connections区域中，选中Break at first line in PHP scripts复选框。

• 启用运行 | 在主菜单中的 PHP 脚本选项中的第一行中断。

要让PhpStorm 在脚本未暂停时显示通知，请在PHP | 设置对话框的调试页面。

使用 nginx 时调试器不起作用

使用nginx$_SERVER["SERVER_NAME"] web 服务器时，如果不是 PHP 提供的，调试可能会失败。为了解决这个问题，fastcgi在 nginx 配置中添加一个参数：

要么

请参阅nginx 文档并在此处查看更多详细信息。

Xdebug 无法连接到 PhpStorm

如果您在 Xdebug 日志中看到以下消息：

要么

这意味着 Xdebug 尝试连接到主机并且无法建立连接。要解决此问题，请设置xdebug.remote_connect_back=0（xdebug.discover_client_host=false对于 Xdebug 3）并确保xdebug.remote_host（xdebug.client_host对于 Xdebug 3）设置正确。

尝试调试框架 CLI 命令会导致 PHP 错误

当尝试调试 PHP 框架命令行工具（例如Symfony Console或Laravel Artisan ）的 CLI 命令时，调试会失败并出现 PHP 错误Fatal error: Class '...\Command' not found"或类似情况。

此类错误的常见原因是尝试直接使用命令调试文件或类。相反，您应该使用PHP 脚本，在其中提供命令行工具的路径和要运行的实际命令。在这种情况下，将应用框架命令引导逻辑，并且调试将正常进行。

有关详细信息，请参阅以下特定于框架的指南：

• 调试 Symfony CLI 命令

• 调试 Artisan CLI 命令

• 调试 Wordpress WP-CLI 命令

• 调试 Drush CLI 命令

Zend Debugger 不会执行删除权限

在 Linux 上使用 Zend Debugger 时，您可能偶尔会看到以下错误：

当调试器无法确定运行 Web 服务器进程的用户的 UID 时，会发生此错误。找到该用户的 UID 并将其添加到php.ini：

更新设置后，重新启动 Web 服务器。

安装 ionCube 进行调试

在某些 PHP 环境中，ionCube用于加载和运行编码的 PHP 代码。ionCube 加载器扩展通过解码要运行的 PHP 代码然后确保 PHP 解释器可以执行它来完成此操作。

正式地，Xdebug 和 Zend Debugger 都不支持在启用 ionCube 的情况下运行，但是有一些解决方法可以尝试。请注意，JetBrains、ionCube、Xdebug 或 Zend Debugger 不支持这些。

• 确保首先加载 ionCube 加载器模块

  在php.ini中，在加载任何调试器扩展之前验证 ionCube 加载器是否已加载，例如：

  zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/ioncube_loader_lin_5.4.so zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525 /xdebug.so

• 使用ionCube按需加载

  我们可以在php.ini中禁用 ionCube 扩展，并利用 ionCube 的按需加载功能。当第一个编码的 PHP 脚本被加载时，PHP 解释器将检查配置extenson_dir以找到 ionCube 扩展并运行编码的 PHP 脚本。

  请注意，此方法不受官方支持。它应该只用于调试目的，绝不能用于生产服务器。