PHPStorm Ubuntu版如何配置Xdebug

PHPStorm Ubuntu版配置Xdebug步骤

1. 安装Xdebug扩展

首先确保系统已安装PHP（通过php -v确认版本），然后安装Xdebug：

sudo apt-get update
sudo apt-get install php-xdebug  # 自动匹配当前PHP版本

若需指定PHP版本（如7.4），可替换为：

sudo apt-get install php7.4-xdebug

2. 配置php.ini文件

找到当前PHP版本的php.ini文件（路径可通过php --ini查看），通常为：

CLI模式：/etc/php/{php_version}/cli/php.ini
FPM模式：/etc/php/{php_version}/fpm/php.ini（如/etc/php/8.1/fpm/php.ini）

用文本编辑器（如nano）打开文件，在末尾添加以下配置：

[Xdebug]
zend_extension=xdebug.so  # Ubuntu下扩展名为.so，无需手动指定路径
xdebug.mode=debug         # 启用调试模式
xdebug.client_host=127.0.0.1  # 调试客户端地址（本地为127.0.0.1）
xdebug.client_port=9003   # 调试端口（Xdebug 3默认9003，需与PHPStorm一致）
xdebug.start_with_request=yes  # 自动启动调试（可选：trigger/yes）
xdebug.idekey=PHPSTORM    # IDE标识（需与PHPStorm设置一致）

保存并退出（Ctrl+O→Enter→Ctrl+X）。

3. 重启Web服务器

配置生效后，需重启PHP和Web服务器：

PHP-FPM（Ubuntu常用）：

sudo systemctl restart php{php_version}-fpm  # 如php8.1-fpm

Apache：
```
sudo systemctl restart apache2
```
Nginx：
```
sudo systemctl restart nginx
```

4. 配置PHPStorm

4.1 设置PHP解释器

打开PHPStorm，进入File > Settings（或PHPStorm > Preferences，macOS）。
导航至Languages & Frameworks > PHP，点击Interpreter右侧的齿轮图标，选择Add。
选择System Interpreter，找到Ubuntu下的PHP路径（如/usr/bin/php），点击OK。

4.2 配置Servers

进入Languages & Frameworks > PHP > Servers，点击+添加新服务器。
输入服务器名称（如Local），设置Host为localhost，Port为80（或你的Web服务器端口，如443）。
勾选Use path mappings（路径映射，后续需配置），点击OK。

4.3 配置Debug设置

进入Languages & Frameworks > PHP > Debug，确保Xdebug部分的Debug port设置为9003（与php.ini一致）。
点击DBGp Proxy标签，设置IDE key为PHPSTORM（与php.ini一致）。

5. 设置路径映射（关键步骤）

路径映射用于关联项目本地路径与服务器上的路径，否则断点无法命中：

在Servers配置中，选中刚添加的服务器，点击Paths标签。
点击+添加映射：
- Local Path：选择项目本地根目录（如/home/user/project）。
- Remote Path：输入服务器上的项目路径（如/var/www/html/project）。
点击Validate验证配置，确保显示“Valid”（所有对勾）。

6. 创建调试配置

点击PHPStorm顶部菜单Run > Edit Configurations。
点击+添加PHP Web Page配置，输入名称（如Xdebug Debug）。
选择刚配置的服务器（如Local），设置Start URL为要调试的页面（如/index.php）。
点击OK保存配置。

7. 测试配置

创建info.php文件，内容为<?php phpinfo(); ?>，上传至服务器。
在浏览器中访问http://localhost/info.php，搜索“Xdebug”，确认Xdebug已启用。
回到PHPStorm，点击顶部工具栏的绿色虫子图标（或Shift+F9）启动调试。
在info.php中设置断点（行号左侧点击），刷新浏览器，断点应命中，进入调试模式。

常见问题排查

断点未命中：检查php.ini中的xdebug.start_with_request是否为yes，client_host是否为127.0.0.1，port是否与PHPStorm一致；确认路径映射是否正确。
Xdebug未加载：运行php -m | grep xdebug，若无输出则说明扩展未加载，需检查zend_extension路径是否正确（Ubuntu下通常为xdebug.so，无需手动指定）。
端口冲突：若9003端口被占用，可修改php.ini中的client_port（如9004），并同步修改PHPStorm的Debug port。