PHPStorm在Ubuntu上如何集成Xdebug

PHPStorm在Ubuntu上集成Xdebug的完整步骤

在Ubuntu环境下，利用PHPStorm进行PHP开发，Xdebug几乎是调试效率的最佳搭档。这篇内容就把整个集成流程拆解清楚，从扩展安装到IDE配置，一步不落。

1. 安装Xdebug扩展

第一步，先确认系统环境没问题。PHP基础环境（比如php-cli、php-fpm或php-apache）要提前装好。之后，用包管理器直接安装Xdebug：

sudo apt update
sudo apt install php-xdebug

装完之后，Xdebug会自动激活，扩展目录也能自动识别。如果不放心，可以用php -i | grep extension_dir确认一下路径。

2. 配置php.ini文件

找到当前PHP版本的php.ini文件。路径可以借助php -i | grep php.ini获取，常见的是/etc/php/8.2/cli/php.ini或/etc/php/8.2/fpm/php.ini。在文件末尾追加以下配置：

[Xdebug]
zend_extension=xdebug.so
; 加载Xdebug扩展（Linux下无需指定完整路径）
xdebug.mode=debug
; 启用调试模式（必填）
xdebug.client_host=127.0.0.1
; 客户端IP（IDE所在机器，本地用127.0.0.1）
xdebug.client_port=9003
; 调试端口（默认9003，需与PHPStorm一致）
xdebug.start_with_request=yes
; 自动启动调试（可选：yes/trigger/never）

需要注意：如果模式设成trigger，调试触发方式就变了——需要在URL后加?XDEBUG_TRIGGER=1参数才能激活调试。

3. 重启Web服务器

配置生效的前提是重启相关服务：

• PHP-FPM（最常用）：

  sudo systemctl restart php8.2-fpm
  ; 记得替换成自己的PHP版本号（8.1、8.0等）

• Apache：

  sudo systemctl restart apache2

• Nginx：

  sudo systemctl restart nginx

4. 验证Xdebug安装

创建一个info.php文件，内容就是。把这个文件放到Web服务器可访问的目录，然后在浏览器里打开。在输出页面搜索“Xdebug”——如果能看到版本信息和配置项（比如client_host、client_port），就说明安装成功了。

5. 配置PHPStorm

5.1 添加PHP解释器

打开PHPStorm，进入File > Settings > PHP，点击“…”按钮，添加本地或远程的PHP解释器。注意确保解释器路径正确，比如/usr/bin/php。

5.2 配置服务器映射

进入File > Settings > PHP > Servers，新建一个服务器配置：

• Name：自定义名称（比如“Local Server”）；
• Host：localhost（或具体服务器IP）；
• Port：80（HTTP）或443（HTTPS）；
• 勾选“Use path mappings”，把项目远程路径（如/var/www/html/myproject）映射到本地路径（如/home/user/projects/myproject）。

5.3 设置调试端口

进入File > Settings > PHP > Debug，确认“Debug port”设置为9003——这必须和php.ini里配的client_port完全一致。

6. 启动调试会话

6.1 设置断点

在代码行号左侧点击，添加一个红色断点。比如在index.php的第10行。

6.2 开启监听

点击PHPStorm右上角的电话图标（“Start Listening for PHP Debug Connections”），IDE就进入等待调试连接的状态。

6.3 触发调试

• 自动触发（start_with_request=yes）：直接在浏览器中访问项目URL（如http://localhost/myproject），代码执行到断点时会自动暂停。
• 手动触发（start_with_request=trigger）：在URL后追加?XDEBUG_TRIGGER=1（如http://localhost/myproject?XDEBUG_TRIGGER=1）来激活调试。

7. 调试操作

代码在断点处暂停后，调试工具栏就是你的主战场：

• Step Over（F8）：执行当前行，跳到下一行；
• Step Into（F7）：进入当前行调用的函数或方法内部；
• Step Out（Shift+F8）：跳出当前函数/方法；
• Resume Program（F9）：继续执行，直到下一个断点或程序结束；
• View Variables：查看当前作用域里的所有变量值；
• Evaluate Expression：直接计算某个表达式的结果。

常见问题排查

• 端口冲突：如果9003被其他进程占用了，别慌。改php.ini里的client_port（比如9004），同时也在PHPStorm的“Debug port”里同步修改即可。
• 路径映射错误：服务器配置里的“Path mappings”一定要准确。一旦映射对不上，断点就无法被正确识别。
• Xdebug未加载：检查php.ini中的zend_extension路径是否正确。也可以通过php -m | grep xdebug来验证扩展有没有加载成功。