PHPStorm 使用 Xdebug 远程调试配置指南 (CentOS7 + 宝塔面板)

一、环境准备

1. 系统安装

• 安装纯净版 CentOS 7.9 系统
• 确保系统基础环境配置完成（网络、防火墙等）

2. 宝塔面板安装

执行以下命令安装最新稳定版宝塔面板：

yum install -y wget && wget -O install.sh http://download.bt.cn/install/install_6.0.sh && sh install.sh

3. 环境组件安装

通过宝塔面板安装以下组件：

• LNMP 架构（默认配置）
• PHP 7.4 版本

二、Xdebug 扩展配置

1. 安装 Xdebug 扩展

通过宝塔面板的 PHP 管理界面安装 Xdebug 扩展

2. 配置 Xdebug

在 PHP 配置文件（php.ini）中添加以下配置：

[xdebug]
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.discover_client_host=true
xdebug.remote_cookie_expire_time=3600
xdebug.client_port=9003
xdebug.client_host="192.168.158.1" ; 改为你的本地开发机IP
xdebug.start_with_request=yes
xdebug.remote_handler="dbgp"
xdebug.log=/tmp/xdebug.log

3. 重启服务

配置完成后必须重启相关服务：

service php-fpm restart
service nginx restart

三、网站环境搭建

1. 通过宝塔面板创建网站
2. 上传项目代码到网站目录
3. 创建并配置数据库
4. 确保网站可以正常访问

四、PHPStorm 配置

1. PHP 设置

• 进入 File > Settings > PHP
• 配置 PHP 解释器路径
• 设置 PHP 语言级别为 7.4

2. DBGp 代理设置

• 进入 File > Settings > PHP > Debug > DBGp Proxy
• 配置 IDE key（与浏览器插件一致）
• 设置 Host 为你的服务器IP
• Port 设置为 9003（与 xdebug.client_port 一致）

3. 调试设置

• 进入 File > Settings > PHP > Debug
• 配置调试端口为 9003
• 勾选 "Break at first line in PHP scripts"

4. 部署与映射

• 进入 Tools > Deployment > Configuration
• 添加服务器配置（SFTP 或 FTP）
• 配置路径映射（本地路径与服务器路径对应）

5. SSH 配置

• 进入 Tools > SSH Configuration
• 添加服务器SSH连接信息
• 测试连接并保存

6. PHP CLI 解释器

• 进入 File > Settings > PHP > CLI Interpreter
• 添加远程解释器
• 配置与服务器相同的PHP版本

五、浏览器配置

1. 安装 Xdebug Helper 插件（Chrome 浏览器）
2. 配置 IDE key（与 PHPStorm 中设置一致）
3. 在需要调试的页面上启用调试模式

六、调试流程

1. 在 PHPStorm 中启动监听（电话图标）
2. 在浏览器中访问目标页面（确保插件已启用调试）
3. 设置断点并开始调试
4. 也可以直接使用 Burp Suite 等工具发包调试

七、常见问题解决

1. 无法拦截调试请求：

   • 检查防火墙是否开放 9003 端口
   • 确认 xdebug.client_host 配置正确
   • 重启 PHP-FPM 和 Nginx 服务
   • 重启 PHPStorm

2. 连接不稳定：

   • 检查网络连接
   • 增加 xdebug.remote_cookie_expire_time 值
   • 检查 /tmp/xdebug.log 日志文件

3. 断点不生效：

   • 确认代码同步（本地与服务器代码一致）
   • 检查路径映射配置
   • 确认 PHPStorm 正在监听调试连接

八、注意事项

1. 生产环境不建议开启 Xdebug，仅限开发测试环境使用
2. 调试完成后建议关闭 Xdebug 或设置 xdebug.start_with_request=trigger
3. 保持 PHPStorm 和 Xdebug 版本兼容
4. 复杂的调试场景可以使用 xdebug.idekey 区分不同开发人员

通过以上完整配置，您应该能够在 PHPStorm 中成功进行远程 Xdebug 调试。如遇问题，建议按照配置步骤逐一检查，并查看 /tmp/xdebug.log 日志文件获取详细错误信息。