PHPStorm在Ubuntu上如何调试PHP代码

在Ubuntu上为PHP项目配置调试环境，是每个开发者提升效率的必经之路。今天，我们就来手把手过一遍，如何让PhpStorm和Xdebug在Ubuntu系统上完美协作，无论是Web请求还是命令行脚本，都能轻松下断点、看变量，让调试过程变得清晰可控。

一 环境准备

工欲善其事，必先利其器。第一步，自然是把基础环境搭建好。

• 安装 PHP 与 Xdebug：这里有个细节需要注意，为了同时支持命令行和Web调试，通常需要为CLI和PHP-FPM各准备一份，并确保版本一致。
  • 先更新包索引，然后安装核心包：sudo apt update && sudo apt install php php-xdebug。
  • 如果系统存在多个PHP版本，记得安装对应版本的Xdebug扩展，例如：sudo apt install php8.1-xdebug。
• 确认 CLI 的 PHP 可执行文件路径：这个路径稍后在PhpStorm中配置解释器时会用到。执行 which php 命令，常见的输出是 /usr/bin/php。
• 可选：安装并启动 Web 服务：如果你需要进行Web请求调试，那么还需要安装Apache或Nginx，并配合PHP-FPM一起使用。

二 配置 Xdebug 3

环境就绪后，接下来是重头戏——配置Xdebug。对于Ubuntu 20.04及以上版本，默认安装的通常是Xdebug 3.x，配置方式与旧版略有不同。

• 找到并编辑对应 SAPI 的 php.ini：配置文件路径因PHP版本和运行模式而异（请将{php_version}替换为你的实际版本号）：
  • CLI模式：/etc/php/{php_version}/cli/php.ini
  • FPM模式：/etc/php/{php_version}/fpm/php.ini
  • Apache模块模式：/etc/php/{php_version}/apache2/php.ini
• 在 php.ini 的 [xdebug] 段落加入配置：确保端口与后续PhpStorm设置保持一致，这里以9003为例：

  zend_extension=xdebug.so
  xdebug.mode=debug
  xdebug.client_host=127.0.0.1
  xdebug.client_port=9003
  xdebug.start_with_request=yes
  xdebug.idekey=PHPSTORM
  

• 重启服务使配置生效：
  • FPM：sudo systemctl restart php{php_version}-fpm
  • Apache：sudo systemctl restart apache2
  • Nginx：sudo systemctl restart nginx
• 验证 Xdebug 已启用：最后，执行 php -v 命令，如果输出信息中包含 “with Xdebug v3.x” 字样，就说明配置成功了。

三 配置 PhpStorm

服务器端搞定，现在轮到IDE了。PhpStorm的配置逻辑清晰，一步步来即可。

• 设置 PHP 解释器：打开 File → Settings → Languages & Frameworks → PHP → CLI Interpreter，点击“…”选择或添加路径，指向刚才查到的 /usr/bin/php。
• 配置 Servers：进入 File → Settings → Languages & Frameworks → PHP → Servers，点击“+”添加：
  • Name：任意名称，比如 localhost。
  • Host：localhost（或你的实际域名/IP）。
  • Port：80（HTTP）或443（HTTPS）。
  • Debugger：选择 Xdebug。
  • 关键一步：勾选 “Use path mappings”。如果你的项目位于虚拟机、容器或远程服务器，必须在这里将本地项目路径准确映射到服务器上的绝对路径。
• 配置 Debug 端口：进入 File → Settings → Languages & Frameworks → PHP → Debug，确认 Debug port 设置为 9003，与php.ini中的配置一致。
• 创建运行/调试配置：点击 Run → Edit Configurations → “+” → PHP Web Page：
  • Name：自定义一个易于识别的名称。
  • Server：选择上一步创建的服务器（如localhost）。
  • Start URL：填写你要调试的页面入口，例如 /index.php。
• 设置断点：在代码编辑区域，找到需要调试的行，在行号左侧单击，出现红色圆点即表示断点设置成功。

四 开始调试

万事俱备，只欠调试。根据你的调试场景，选择对应的启动方式。

• Web 调试（Apache/Nginx + FPM）
  • 在PhpStorm中，点击工具栏上的绿色“甲虫”图标，或直接按 Shift+F9，启动调试监听。
  • 用浏览器访问你的网站页面。如果调试没有自动触发，可以在URL后面手动追加参数：?XDEBUG_SESSION_START=PHPSTORM。
  • 当执行到断点处时，程序会暂停，此时可以在PhpStorm中查看变量值、调用栈，并使用 F7（步入）、F8（步过）、Shift+F8（步出）控制代码执行流程。
• CLI 调试（命令行脚本）
  • 为命令行脚本创建调试配置：Run → Edit Configurations → “+” → PHP Script，指定要调试的脚本文件路径。
  • 直接点击调试按钮运行，脚本执行到断点处便会自动暂停。
• 浏览器便捷触发（可选）
  • 可以给浏览器安装“Xdebug Helper”这类扩展。安装后，将IDE key设置为 PHPSTORM，之后只需点击浏览器工具栏上的扩展图标，即可快速开启或关闭调试会话，非常方便。

五 常见问题排查

配置过程很少一帆风顺，遇到问题别慌，按以下思路排查，基本都能解决。

• 端口被占用：执行 lsof -i :9003 查看是哪个进程占用了9003端口，将其关闭，或者在php.ini和PhpStorm中统一改用另一个空闲端口。
• 断点不被命中
  • 确认你通过浏览器访问的是由PHP-FPM处理的网站，而不是在终端直接执行PHP脚本。
  • 检查PhpStorm中Servers配置的Host、Port，尤其是“路径映射”是否设置正确。
  • 确认php.ini中Xdebug的配置为 xdebug.mode=debug，且 client_host 和 client_port 指向正确。
• 多版本 PHP：确保命令行（CLI）、PHP-FPM、修改的php.ini文件以及PhpStorm中选择的解释器，都是同一个PHP版本。
• 日志定位
  • 查看Web服务错误日志：journalctl -u apache2 或 journalctl -u nginx。
  • 启用Xdebug日志：在php.ini中增加 xdebug.log=/tmp/xdebug.log 并重启服务，然后查看该日志文件，里面记录了Xdebug尝试连接IDE的详细握手过程，是排查连接问题的利器。