phpstorm在Debian中如何配置Xdebug

在 Debian 中配置 PhpStorm 与 Xdebug 的完整步骤

说实话，配置 Xdebug 这件事，不少开发者都觉得有点折腾，尤其是在 Linux 环境下，很容易因为一个端口不对或者路径映射没搞对，就卡住半天。其实整个流程是有章可循的，关键在于把几个基础步骤踩实了。下面我们就一步步来梳理。

一 准备与版本确认

在动手之前，先把基础信息确认清楚，这事儿永远不亏。

• 确认 PHP 版本和 SAPI：运行 php -v 可以看版本，用 php -m | grep -E 'apache2|fpm' 能知道当前用的是哪种 SAPI（比如 Apache 模块还是 PHP-FPM）。这个信息直接决定了后续要配置哪个 php.ini。
• 安装对应版本的 Xdebug：假设你用的是 PHP 8.2，直接 sudo apt update && sudo apt install php8.2-xdebug。版本要对得上，比如 PHP 7.4 就要装 php7.4-xdebug，以此类推。

二 配置 Xdebug 3（Debian 常见默认）

Xdebug 3 的配置比之前版本简洁了不少，核心是找到正确的 php.ini 文件。需要留意的是，不同 SAPI 的配置路径不一样：

• Apache：编辑 /etc/php/8.2/apache2/php.ini
• PHP-FPM（Nginx）：编辑 /etc/php/8.2/fpm/php.ini
• CLI：编辑 /etc/php/8.2/cli/php.ini

在对应文件的末尾添加上以下配置（端口统一用 9003）：

[xdebug]
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

保存之后别忘了重启服务：

• Apache：sudo systemctl restart apache2
• PHP-FPM + Nginx：sudo systemctl restart php8.2-fpm && sudo systemctl restart nginx
• CLI 环境下不需要重启，但要确认 CLI 与 Web 用的是同一套 php.ini 配置（或者分别配置好）。

三 配置 PhpStorm

PhpStorm 这边的设置同样重要，几个关键位置要一一对应上。

• 打开设置：File → Settings（macOS 是 Preferences）→ Languages & Frameworks → PHP → Debug，将 Debug port 设为 9003，保证和之前 php.ini 里的 xdebug.client_port 一致。
• 配置 DBGp Proxy：在同一菜单下找到 DBGp Proxy，IDE key 填 PHPSTORM，Host 填 localhost，Port 填 9003。
• 配置服务器：进入 Languages & Frameworks → PHP → Servers，点 + 新建一个。Name 可以随便填（比如 localhost），Host 填你的站点域名或者 localhost，Port 填 80 或 443，Debugger 选 Xdebug。最关键的是勾选 Use path mappings，将本地项目根路径映射到服务器上的实际路径（比如部署在 /var/www/html 就填那个目录）。
• CLI 解释器（可选但推荐）：在 Languages & Frameworks → PHP → CLI Interpreter 中选择或添加你的 PHP 可执行文件，比如 /usr/bin/php8.2。

四 启动调试与触发方式

一切配置就绪，接下来就是实际操练了。

• 在 PhpStorm 中点击工具栏上的电话听筒图标，开启 Start Listening for PHP Debug Connections。
• 触发调试有两种靠谱的方式：
• 浏览器扩展：安装 Xdebug Helper 这类扩展，选择 IDE Key 为 PHPSTORM，然后正常访问页面，断点就会被命中。
• 手动触发：在 URL 后面加上 ?XDEBUG_SESSION_START=PHPSTORM，或者在请求中携带 Cookie XDEBUG_SESSION=PHPSTORM。
• 调试会话控制：在代码行号左侧单击可以设置断点，命中断点后用 Step Over/Into/Out 进行单步调试，随时查看 Variables 和 Call Stack。继续执行点击 Resume Program（F9）。

五 常见问题排查

配置过程中难免遇到一些小问题，这里列几个经常遇到的，可以节省不少排查时间。

• 端口被占用：用 sudo ss -lntp | grep 9003 检查一下。如果端口被占用了，可以在 php.ini 和 PhpStorm 里同步改成别的端口（比如 9010）。
• 连接失败或无法命中断点：最常见的原因是 Web 和 CLI 用的 php.ini 不一致，或者 Path mappings 映射错了。另外，DBGp Proxy 的 IDE key、Host、Port 要和 php.ini 里的配置保持完全一致。也可以去翻一下 Web 服务的错误日志（Apache 在 /var/log/apache2/error.log，Nginx 在 /var/log/nginx/error.log），以及 php-fpm 的日志，往往能直接看出问题。
• 远程/容器/虚拟机调试：这种情况需要把 xdebug.client_host 设置成 IDE 所在机器的 IP（比如宿主机或开发机的 IP），并且要确保网络是通的。注意，如果 IDE 和 Web 服务不在同一台机器上，千万不要再用 127.0.0.1，必须用实际可达的 IP 地址。