PHPStorm Ubuntu版如何集成Xdebug

在 Ubuntu 上把 Xdebug 与 PhpStorm 集成，按下面 5 步即可完成

一 安装 Xdebug 扩展

首先，你需要确保系统安装了与当前 PHP 版本匹配的 Xdebug 扩展。操作其实很简单：更新软件包索引，然后安装对应的扩展包。常见的包名是 php-xdebug 或者带版本号的 php{version}-xdebug。

动手前，别忘了先确认一下你的 PHP 版本，命令就是 php -v。安装示例命令通常是：sudo apt-get update && sudo apt-get install php-xdebug。

安装完成后，怎么验证呢？有两个快速的方法：运行 php -m | grep xdebug 看输出列表，或者直接看 php -v 命令的返回信息里是否包含 “with Xdebug”。如果没加载成功，那很可能是扩展没安装到正确的 SAPI（比如 CLI、FPM 或 Apache 模块）环境下，需要检查一下。

二 配置 Xdebug 参数

接下来是配置环节，这一步决定了 Xdebug 如何工作。你需要编辑对应 SAPI 的 PHP 配置文件。路径会因 PHP 版本和运行方式而异，常见位置是 /etc/php/{version}/{sapi}/php.ini。另一种更清晰的做法是在 /etc/php/{version}/mods-a vailable/xdebug.ini 里统一配置，然后通过软链接启用。

这里有个实用建议：为了不影响命令行交互，推荐仅对 Web 请求启用调试。关键的配置项包括：

• zend_extension=xdebug.so
• xdebug.mode=debug
• xdebug.client_host=127.0.0.1
• xdebug.client_port=9003
• xdebug.start_with_request=trigger；这样在浏览器访问时，需要在 URL 后添加 ?XDEBUG_TRIGGER 参数来手动触发调试。

需要留意几个细节：端口 9003 是 Xdebug 3 的默认设置。如果它和本地的 php-fpm 服务端口（默认 9000）冲突了，可以改为其他端口（比如 9000），但务必记得在 PhpStorm 里也同步修改监听端口。另外，如果是进行远程或容器内调试，需要把 client_host 改为宿主机或容器能够访问到的 IP 地址。

三 配置 PhpStorm

现在，把目光转向 PhpStorm。要让 IDE 和 Xdebug 联动起来，需要完成以下几项设置：

首先，设置 PHP 解释器：进入 File > Settings > Languages & Frameworks > PHP > Interpreters，选择你系统上的 PHP 可执行文件路径，通常是 /usr/bin/php 或对应版本。

接着，配置服务器信息：在 Languages & Frameworks > PHP > Servers 里，点击 “+” 添加。填写服务器名称（Name）、主机地址（Host，如 localhost）和端口（Port，如 80 或 443）。关键一步是勾选 “Use path mappings”，将你本地的项目目录路径精确映射到服务器上的对应路径（例如，本地 /var/www/html 映射到服务器 /var/www/html）。

然后，配置调试选项：进入 Languages & Frameworks > PHP > Debug，确保已经启用了 Xdebug，并且端口设置（比如 9003）与上一步 php.ini 里的配置完全一致。

最后，创建一个运行配置：点击 Run > Edit Configurations > + > PHP Web Page，选择刚才创建好的服务器，保存即可。

四 启动调试与验证

一切就绪，可以开始实战调试了。在你感兴趣的代码行号左侧点击，设置一个断点。然后，点击 PhpStorm 工具栏上那个绿色的虫子图标（或者直接按 Shift+F9）启动调试监听。

如何触发调试会话呢？分两种情况：

• Web 请求：用浏览器访问目标 URL。如果你在配置中设置了 xdebug.start_with_request=trigger?XDEBUG_TRIGGER 参数。
• 命令行脚本：可以直接在 PhpStorm 里运行或调试这个脚本；如果在终端执行，则需要先设置环境变量：export XDEBUG_SESSION=1。

当代码执行到你设置的断点时，程序会暂停。这时，你就可以使用调试工具栏的按钮进行“单步跳过”（F8）、“单步进入”（F7）、“单步跳出”（Shift+F8）等操作了，同时在 Variables（变量）和 Call Stack（调用栈）面板里观察程序的状态，这才是调试的乐趣所在。

五 常见问题排查

当然，集成过程偶尔也会遇到一些小麻烦。这里列举几个常见问题及其排查思路：

端口冲突：如果默认的 9000 端口被 php-fpm 占用了，解决方案是把 Xdebug 和 PhpStorm 的端口统一改为 9003 或其他未被占用的端口。同时，也要注意避免和 IDE 内部其他服务的端口产生冲突。

断点未生效：如果代码执行没有在断点处停下，可以按以下顺序检查：

• 核对 php.ini 中的 client_host 和 client_port 是否与 PhpStorm 中的设置一字不差。在远程或容器调试场景下，务必确保 client_host 设置的 IP 是可达的。
• 确认你修改的是实际在用的 SAPI 配置文件。比如，如果你用 FPM，改的就是 /etc/php/{version}/fpm/php.ini，修改后别忘了重启 php-fpm 服务。
• 重启相关的 Web 服务：sudo systemctl restart apache2 或 sudo systemctl restart php{version}-fpm（如果用了 Nginx，通常重启 PHP-FPM 即可）。

验证配置是否生效：最直接的方法是创建一个 phpinfo() 页面，在输出内容里查找是否有 Xdebug 相关的段落。或者，在命令行运行 php -i | grep xdebug，查看扩展是否加载以及关键参数是否正确。