ubuntu phpstorm怎么配xdebug

在 Ubuntu + PhpStorm 下配置 Xdebug 一般分为三步：安装 Xdebug、配置 php.ini、配置 PhpStorm。下面以 PHP 8.x + Xdebug 3.x 为例（最常见）。

一、安装 Xdebug

1. 通过 apt 安装（推荐）

sudo apt update
sudo apt install php-xdebug

安装后一般会在：

/etc/php/8.x/cli/conf.d/20-xdebug.ini
/etc/php/8.x/apache2/conf.d/20-xdebug.ini

或

/etc/php/8.x/fpm/conf.d/20-xdebug.ini

二、配置 php.ini（Xdebug 3）

1. 编辑 Xdebug 配置文件

sudo nano /etc/php/8.x/cli/conf.d/20-xdebug.ini

（如果是 web 调试，改 apache2 或 fpm 下的）

2. 写入以下内容（最常用配置）

zend_extension=xdebug.so

[Xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

⚠️ Xdebug 3 默认端口是 9003（老版本是 9000）

3. 重启服务

# Apache
sudo systemctl restart apache2

# 或 PHP-FPM
sudo systemctl restart php8.x-fpm

4. 验证是否安装成功

php -v

看到类似：

with Xdebug v3.x

说明成功。

三、配置 PhpStorm

1. 设置 PHP 解释器

File → Settings → PHP

CLI Interpreter：选择你的 PHP
点击 ... → 确保 Xdebug 被识别

2. 配置 Debug 端口

Settings → PHP → Debug

Debug port：9003
勾选 Can accept external connections

3. 配置 DBGp Proxy（可选但推荐）

Settings → PHP → Debug → DBGp Proxy

IDE key: PHPSTORM
Host: 127.0.0.1
Port: 9003

4. 开启监听

工具栏点击：

▶▶ Start Listening for PHP Debug Connections

四、浏览器触发调试

方法 1：书签（推荐）

访问： https://www.jetbrains.com/phpstorm/marklets/

生成：

Start Debug
Stop Debug

点击 Start Debug 后访问你的项目。

方法 2：GET 参数

http://localhost/project/?XDEBUG_SESSION=PHPSTORM

五、常见问题

❌ 断点不生效

确认 xdebug.mode=debug
确认 PhpStorm 在监听
确认端口一致（9003）

❌ 浏览器一直转圈

关闭 start_with_request=yes
改为：

xdebug.start_with_request=trigger

六、总结（最小可用配置）

xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.idekey=PHPSTORM

如果你用的是 Docker / WSL / Laravel / Nginx，告诉我，我可以给你针对性配置。