在 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 安装：sudo yum install -y gcc php-devel php-pear autoconf && sudo pecl install xdebug
- 或源码编译（示例版本 2.5.0，仅作演示）：
- 下载与编译：wget http://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/
- 重启服务使环境生效：sudo systemctl restart httpd 或 sudo systemctl restart php-fpm。
二 配置 Xdebug
- 编辑 PHP 配置（路径可能为 /etc/php.ini 或 /etc/php.d/xdebug.ini；CLI 与 FPM 可能分别有配置，建议保持一致）。
- 按 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
- 设置 PHP 解释器：File → Settings → Languages & Frameworks → PHP → CLI Interpreter，选择本机或 SSH Interpreter（远程服务器上的 /usr/bin/php）。
- 配置服务器与路径映射：File → Settings → Languages & Frameworks → PHP → Servers → +，填写 Name/HOST/Port，勾选 Use path mappings，将本地项目路径映射到服务器路径（如本地 /home/user/project → 远程 /var/www/html/project）。
- 创建运行配置：Run → Edit Configurations → + → PHP Web Page，选择上一步的 Server，设置 Debug port=9003；在 Run/Debug Configurations 中确认 IDE key=PHPSTORM。
- 启动监听：点击工具栏的 电话听筒图标（Start Listening for PHP Debug Connections）。
四 开始调试
- 浏览器触发调试：
- 手动触发：访问 http://服务器IP/your.php?XDEBUG_SESSION_START=PHPSTORM
- 插件触发：安装浏览器扩展（如 Xdebug Helper），选择 IDE Key 为 PHPSTORM 后一键开启
- 触发后，PhpStorm 会在断点处暂停，可使用 变量查看、调用堆栈、表达式评估、单步执行 等调试工具进行分析。
五 常见问题与排查
- 端口与防火墙：
- 确保端口 9003 未被占用（如被占用，修改 Xdebug 与 PhpStorm 的端口为 9001/9003 等未占用端口）
- 开放防火墙：sudo firewall-cmd --zone=public --add-port=9003/tcp --permanent && sudo firewall-cmd --reload
- 路径映射：断点不生效时，优先核对 Servers 中的本地与远程路径映射 是否准确
- 版本兼容：Xdebug 3.x 与 2.x 参数差异较大，切勿混用；不确定版本时，先执行 php -v 与 php --ri xdebug 确认
- 连接日志：开启 Xdebug 日志定位问题（如 xdebug.remote_log=/tmp/xdebug.log 或 Xdebug 3 的日志配置），检查是否成功连接或被拒绝
- 端口冲突：若 9000 被 PHP-FPM 占用，优先改用 9003 并同步修改 PhpStorm 的 Debug port。