排查常见 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 之间的原始通信以及任何警告或错误：

   Log opened at 2018-01-08 08:14:28 I: Connecting to configured address/port: 127.0.0.1:9000. I: Connected to client. :-) -> <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 by Derick Rethans]]></copyright></init> <- step_into -i 5 -> <response xmlns="urn:debugger_protocol_v1" xmlns:xdebug="https://xdebug.org/dbgp/xdebug" command="step_into" transaction_id="5" status="break" reason="ok">< xdebug:message filename="file:///C:/Projects/Samples/DebuggingTutorial/debugging.php" lineno="2"></xdebug:message></response>

确保已安装并配置 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.client_host 和 xdebug.client_port ）是正确的。 有关更多信息，请参阅 Xdebug 文档。

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

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

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

• 在 PhpStorm 中，通过执行以下任一操作启用监听传入的调试连接：

  • 单击工具栏/状态栏上的 。

  • 在主菜单中选择 运行 | 开始侦听PHP 调试连接。

  这确保了当在 Web 服务器上启动调试会话时，PhpStorm 会做出反应并自动打开 调试工具窗口。 在开始调试会话之前，请确保已设置 断点或在 Debug 对话框的 设置 页面上启用了 在PHP 脚本中的第一行中断 选项 Ctrl+Alt+S。

• 验证是否有防火墙、路由器或 ISP 阻止了连接。 可以通过从远程服务器运行 telnet host 9000 (for Xdebug) 或 telnet host 10137 （适用于 Zend Debugger）（其中主机是运行 PhpStorm 的本地计算机的 IP 地址）并检查是否建立了连接来验证。 您可以使用 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 已从调试会话中分离

在某些情况下，Xdebug 的逐步调试器会正确激活，但 PhpStorm 决定不继续处理请求，并从调试会话中分离。 在这种情况下，PhpStorm 的 调试日志文件和 Xdebug 的日志文件将包含一条错误消息，指明发生分离的原因：

• File is under skipped path

  Xdebug 尝试调试的文件位于 PhpStorm 设置中的 PHP | Debug | 跳过的路径 下。 要调试该文件，请将其从 跳过的路径 列表中删除。

• File is a phpinfo helper script

  分离是由于 Xdebug 干预了 phpinfo.php 文件，该文件是 PhpStorm 中的一个辅助脚本。

• File is under skipped path or a phpinfo helper script

  见上文。

• Debugging session ended

  PhpStorm 与 Web 服务器之间的连接状态由于调试会话结束而更改为 disconnected。

• Cannot bind file to the web server project

  PhpStorm 已连接到 Web 服务器，但无法将监听此调试连接的 PhpStorm 项目映射到 Web 服务器上的项目。

• External connection stopped working

  PhpStorm 与 Web 服务器之间的连接丢失。

• No external connection found

  PhpStorm 未能找到已注册的外部 Xdebug 连接。

• Project lost

  PhpStorm 项目在调试会话中途被关闭。

• Error occurred

  请参阅错误描述以了解详细信息。

未配置调试服务器

如果在未配置 调试服务器的情况下启动零配置调试会话，则在建立连接时，PhpStorm 会显示 传入连接对话框 ，建议从 服务器访问配置 （部署配置 ）中导入映射。 如果选择 从部署导入映射(I) ，PhpStorm 会尝试检测最合适的部署配置，在 部署 列表中预选它，并且 预览区域 会显示项目文件的绝对路径，该路径根据所选配置的映射对应于当前执行的脚本。

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

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

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

您还可以选择 手动选择本地文件或项目(M) 选项，在这种情况下，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 行后续代码，停在有可执行代码的行，并将断点定义更新为该行。

如果您不希望 PhpStorm 在调试会话期间解析和移动断点，可以在 PHP | 调试 页面的 设置 对话框（Ctrl+Alt+S ）中禁用此功能。

在 Xdebug 区域：

• 取消选中 如果断点在当前行不可用，则解析断点（Xdebug 2.8+） 复选框以禁用整个断点解析功能。 请注意，如果禁用了解析，则设置在没有可执行代码的代码行上的断点将始终被忽略。

• 取消选中 如果断点位置与源代码不同，则移动断点到解析位置 复选框以仅禁用断点位置自动调整到 Xdebug 实际停止的行。 请注意，断点解析功能仍将启用。

在 设置 区域，取消选中 在断点解析到不同的行时通知（Xdebug 2.8+） 复选框以关闭 PhpStorm 每次解析断点时的通知。

脚本未被挂起

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

• 通过单击代码中所需可执行行的边距设置断点。 有关更多信息，请参见 断点。

• 在 设置 对话框（Ctrl+Alt+S ）中，转到 PHP | 调试 ，并在 外部连接 区域中选中 在PHP 脚本中的第一行中断 复选框。

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

要让 PhpStorm 显示通知以提示脚本未挂起，请在 高级设置 区域的 PHP | 调试 页面上的 设置 对话框中选中 在调试会话完成而不暂停时通知 复选框。

使用 nginx 时调试器无法工作

使用 nginx Web 服务器时，如果 PHP 未提供 $_SERVER["SERVER_NAME"] ，调试可能会失败。 为解决此问题，请在 nginx 配置中添加 fastcgi 参数：

或

有关更多信息，请参阅 nginx 文档和 此社区帖子。

Xdebug 无法连接到 PhpStorm

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

或

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

尝试调试框架 CLI 命令时出现 PHP 错误

尝试调试 PHP 框架命令行工具的 CLI 命令（例如 Symfony Console或 Laravel Artisan ）时，调试因 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 解释器将检查配置的 extension_dir 以找到 ionCube 扩展并运行编码的 PHP 脚本。

  请注意，此方法并未获得官方支持。 它仅应用于调试目的，绝不能在生产服务器上使用。