在 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，或者在请求中携带 CookieXDEBUG_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 地址。
