PHPStorm Ubuntu版如何配置Xdebug

时间：2026-07-21

PHPStorm Ubuntu版配置Xdebug步骤

配置Xdebug，Ubuntu + PHPStorm这套组合是很多开发者的标配。但说实话，配置过程里的坑确实不少，尤其是路径映射和端口设置，稍不留神就容易翻车。下面直接上干货，把整个流程拆解清楚。

1. 安装Xdebug扩展

第一步，先把Xdebug扩展装上。前提是系统里已经装好了PHP，用php -v确认一下版本号。然后执行：

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.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。

用文本编辑器打开，在末尾加上这段配置：

[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服务器

配置写完了，重启一下服务才能生效。根据你用的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

服务端搞定了，该轮到PHPStorm登场了。这部分分成三步走。

4.1 设置PHP解释器

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

4.2 配置Servers

进入Languages & Frameworks > PHP > Servers，点击+添加新服务器。
输入服务器名称（比如Local），Host填localhost，Port填你的Web服务器端口（默认80，如果是HTTPS则443）。
勾选Use path mappings（路径映射，这一步很关键，后面会详细说），点OK。

4.3 配置Debug设置

进入Languages & Frameworks > PHP > Debug，确保Xdebug部分的Debug port设置为9003——这个必须和php.ini里的client_port一致。
点击DBGp Proxy标签，设置IDE key为PHPSTORM，同样要和php.ini里的idekey保持一致。

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文件，内容就写，把它放到服务器上。
在浏览器里访问http://localhost/info.php，搜索“Xdebug”这个关键词，确认Xdebug已经启用。
回到PHPStorm，点击顶部工具栏的绿色虫子图标（或者按Shift+F9）启动调试。
在info.php里随便找个位置设置断点（行号左侧点一下），然后刷新浏览器。如果断点成功命中，进入调试模式，那就说明大功告成了。

常见问题排查

真遇到问题也别慌，常见的坑其实就那几个：

断点未命中：检查php.ini里xdebug.start_with_request是不是yes，client_host是不是127.0.0.1，端口号和PHPStorm里设置的是否一致。路径映射有没有配错，再仔细核对一遍。
Xdebug未加载：运行php -m | grep xdebug，如果没输出，说明扩展根本没加载。检查一下zend_extension的路径对不对——Ubuntu下通常是xdebug.so，不需要手动指定完整路径。
端口冲突：如果9003端口被别的程序占用了，可以改个端口号。比如把php.ini里的client_port改成9004，同时把PHPStorm的Debug port也改成9004，两边保持一致就行。