在 CentOS 上使用 PhpStorm 调试的完整步骤
一 环境准备与安装
万事开头难，调试环境的搭建是第一步，也是最关键的一步。别担心，跟着步骤走，其实并不复杂。
- 安装 Web 与 PHP 运行环境：这里以经典的 Apache + PHP-FPM 组合为例。如果你用的是 Nginx，操作大同小异，只是在重启服务时，将对应的命令替换为重启 php-fpm 即可。
- 安装命令非常简单，一行搞定：
sudo yum install -y httpd php php-cli php-pear php-devel
- 安装命令非常简单，一行搞定：
- 安装 Xdebug：这是调试的核心。推荐使用与你的 PHP 版本匹配的 PECL 包安装，这是最便捷的方式。如果你的系统版本较旧，PECL 源里没有合适的包，那么源码编译就是备选方案。
- PECL 安装：先安装编译工具，再通过 pecl 安装：
sudo yum install -y gcc php-devel php-pear autoconf && sudo pecl install xdebug - 或源码编译（这里以 2.5.0 版本为例，仅作演示，请根据实际情况调整）：
- 下载与编译：
wget https://xdebug.org/files/xdebug-2.5.0.tgz && tar xvzf xdebug-2.5.0.tgz && cd xdebug-2.5.0 && phpize && ./configure --enable-xdebug && make - 复制模块：
sudo cp modules/xdebug.so /usr/lib64/php/modules/
- 下载与编译：
- PECL 安装：先安装编译工具，再通过 pecl 安装：
- 最后，别忘了让所有配置生效：
sudo systemctl restart httpd或sudo systemctl restart php-fpm。
二 配置 Xdebug
安装只是第一步，正确的配置才是调试能跑起来的关键。这里有个常见的“坑”需要特别注意：Xdebug 2.x 和 3.x 的配置参数名完全不同，千万别混用。
- 首先，找到 PHP 的配置文件进行编辑。路径通常是
/etc/php.ini，也可能在/etc/php.d/xdebug.ini。注意，CLI（命令行）和 FPM（Web服务）可能使用不同的配置文件，为了调试体验一致，建议都进行配置。 - 然后，根据你的 Xdebug 版本，写入对应的参数。对照下表，一目了然：
| 参数 | Xdebug 3.x | Xdebug 2.x |
|---|---|---|
| 启用扩展 | zend_extension=/usr/lib64/php/modules/xdebug.so | zend_extension=/usr/lib64/php/modules/xdebug.so |
| 调试模式 | xdebug.mode=debug | xdebug.remote_enable=1 |
| 客户端主机 | xdebug.client_host=127.0.0.1 | xdebug.remote_host=127.0.0.1 |
| 调试端口 | xdebug.client_port=9003 | xdebug.remote_port=9003 |
| 触发方式 | xdebug.start_with_request=yes | xdebug.remote_autostart=1 |
| IDE Key | xdebug.idekey=PHPSTORM | xdebug.idekey=PHPSTORM |
- 保存配置文件后，老规矩，重启服务让配置生效：
sudo systemctl restart httpd或sudo systemctl restart php-fpm。
三 配置 PhpStorm
服务器端准备好了，现在轮到我们的“作战指挥中心”——PhpStorm 登场了。这里的配置核心就两点：告诉 PhpStorm 代码在哪里运行，以及如何与 Xdebug 对话。
- 设置 PHP 解释器：进入
File → Settings → Languages & Frameworks → PHP → CLI Interpreter。这里可以选择本地解释器，如果代码在远程服务器上运行，就配置一个 SSH Interpreter，指向服务器上的/usr/bin/php。 - 配置服务器与路径映射：这是断点能否生效的重中之重。进入
File → Settings → Languages & Frameworks → PHP → Servers，点击+添加。填写服务器名称、主机地址和端口。最关键的一步：务必勾选Use path mappings，然后将你本地的项目目录路径，精确映射到服务器上的网站根目录（例如：本地/home/user/project→ 远程/var/www/html/project）。 - 创建运行配置：点击
Run → Edit Configurations → + → PHP Web Page。选择上一步创建的 Server，并将 Debug port 设置为 9003（与 Xdebug 配置保持一致）。同时，在 Run/Debug Configurations 中确认 IDE key 为 PHPSTORM。 - 启动监听：最后，点击 PhpStorm 工具栏上那个小小的电话听筒图标（Start Listening for PHP Debug Connections），让它变成绿色，表示已经准备好接收调试连接了。
四 开始调试
一切就绪，激动人心的调试时刻到了。如何触发调试会话呢？主要有两种方式：
- 浏览器触发调试：
- 手动触发：直接在浏览器地址栏访问你的 PHP 文件，并在 URL 后加上参数，例如：
https://服务器IP/your.php?XDEBUG_SESSION_START=PHPSTORM。 - 插件触发（推荐）：为浏览器安装一个叫 “Xdebug Helper” 的扩展。安装后，在浏览器工具栏点击它的图标，将 IDE Key 选择为 PHPSTORM，然后点击“调试”按钮即可一键开启，比手动加参数方便得多。
- 手动触发：直接在浏览器地址栏访问你的 PHP 文件，并在 URL 后加上参数，例如：
- 一旦触发成功，PhpStorm 会自动捕获到请求，并在你预设的断点处暂停。接下来，你就可以尽情使用变量查看窗口、调用堆栈面板、表达式评估和单步执行（Step Over, Step Into）等强大的调试工具，像外科手术一样剖析你的代码逻辑了。
五 常见问题与排查
理想很丰满，现实有时会出点小状况。如果调试没按预期工作，别慌，按照下面这个清单逐一排查，十有八九能找到问题所在。
- 端口与防火墙：
- 首先确认端口 9003 没有被其他程序占用。如果被占用了（比如旧版的 PHP-FPM 默认使用 9000 端口，也可能冲突），可以修改 Xdebug 配置和 PhpStorm 中的 Debug port，换到 9001 或其他未被占用的端口。
- 服务器防火墙可能阻止了连接。记得开放对应的端口：
sudo firewall-cmd --zone=public --add-port=9003/tcp --permanent && sudo firewall-cmd --reload
- 路径映射：这是断点不生效的最常见原因。请立刻返回 PhpStorm 的 Servers 配置，反复核对本地路径与远程服务器路径的映射关系是否 100% 准确。
- 版本兼容：再次强调，Xdebug 3.x 与 2.x 的参数差异巨大，配置时务必对号入座，切勿张冠李戴。如果不确定版本，在服务器上执行
php -v和php --ri xdebug命令就能一目了然。 - 连接日志：当问题比较隐蔽时，开启 Xdebug 的日志功能是终极定位手段。在配置中添加日志路径（Xdebug 2.x:
xdebug.remote_log=/tmp/xdebug.log；Xdebug 3.x 查看对应日志配置），然后查看日志文件，里面会详细记录连接是否成功、为何被拒绝等信息。 - 端口冲突：如果 PHP-FPM 已经占用了 9000 端口，强烈建议将 Xdebug 的调试端口改为 9003，并同步修改 PhpStorm 中的配置，这是避免冲突的最佳实践。
