Debian下phpstorm如何配置Xdebug

Debian 下 PhpStorm 配置 Xdebug 实战指南

一环境准备与安装

确认 PHP 版本：运行命令查看版本与 SAPI（如 apache2、fpm）
- 查看版本：php -v
- 查看 SAPI：php -m | grep -E 'apache2|fpm'
安装 Xdebug（选择与当前 PHP 版本匹配的包）
- Debian 11/12 常见：sudo apt-get update && sudo apt-get install php-xdebug
- 多版本并存时安装对应版本：sudo apt-get install php8.2-xdebug（示例为 8.2）
启用扩展
- 推荐方式（模块化配置）：编辑 /etc/php/8.2/mods-available/xdebug.ini，添加配置后执行 sudo phpenmod xdebug
- 或直接编辑对应 SAPI 的 php.ini（如 /etc/php/8.2/apache2/php.ini、/etc/php/8.2/cli/php.ini）
重启服务使配置生效
- Apache：sudo systemctl restart apache2
- PHP-FPM：sudo systemctl restart php8.2-fpm
- Nginx+PHP-FPM：重启 php8.2-fpm 与 nginx
验证安装
- php -m | grep -i xdebug 应看到 xdebug
- php -v 首行应出现 with Xdebug v3.x 字样

二 Xdebug 3 关键配置

编辑 Xdebug 配置（建议集中在 /etc/php/8.2/mods-available/xdebug.ini）
- 最简可用（本机或同网段开发机调试）：
```
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes
```
- 服务器/容器场景（让 Xdebug 自动发现 IDE 主机）：
```
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.discover_client_host=true
xdebug.client_port=9003
xdebug.start_with_request=yes
```
- 如需触发式调试（仅在特定请求时连接 IDE），将 xdebug.start_with_request 设为 trigger，并在请求中携带触发参数（如 XDEBUG_SESSION=PHPSTORM）。
端口与防火墙
- 默认调试端口为 9003，确保该端口在服务器防火墙与云安全组放行
- UFW 示例：sudo ufw allow 9003/tcp
- firewalld 示例：sudo firewall-cmd --add-port=9003/tcp --permanent && sudo firewall-cmd --reload

三 PhpStorm 调试器设置

解释器与调试端口
- File → Settings → Languages & Frameworks → PHP → CLI Interpreter：选择或新增本机 PHP 可执行文件（如 /usr/bin/php8.2）
- File → Settings → Languages & Frameworks → PHP → Debug：将 Debug port 设为 9003（与 xdebug.client_port 一致）
服务器映射（Servers）
- File → Settings → PHP → Servers：新增服务器
  - Name：自定义（如 MyApp）
  - Host：服务器域名或 localhost
  - Port：80/443
  - Debugger：Xdebug
  - 勾选 Use path mappings，将项目根目录映射到服务器部署目录（如 /var/www/html → 本地项目根）
DBGp Proxy（可选，团队协作/多 IDE 时）
- File → Settings → PHP → Debug → DBGp Proxy
  - IDE key：PHPSTORM
  - Host：IDE 所在主机 IP
  - Port：9003
启动调试
- 点击工具栏 Start Listening for PHP Debug Connections（电话图标）
- 浏览器访问应用触发断点，或在 CLI/单元测试中运行脚本

四触发调试与常见问题

触发方式
- 浏览器调试：安装 Xdebug Helper（Chrome/Edge），IDE Key 选 PHPSTORM，访问页面即可命中断点
- API/命令行/Postman：在请求中携带 Cookie 或参数
  - Cookie：XDEBUG_SESSION=PHPSTORM
  - GET/POST 参数：XDEBUG_SESSION_START=PHPSTORM
常见问题排查
- 端口不通：确认服务器与 IDE 所在机器 9003 可达（telnet IDE_IP 9003 或 nc -vz IDE_IP 9003）
- 未命中断点：检查 Servers 路径映射是否正确；CLI 与 Web 的 php.ini 是否都加载了 Xdebug
- 多 PHP 版本：确认安装与启用的 Xdebug 与运行的 PHP 版本/SAPI一致（如 php8.2-fpm 对应 php8.2-xdebug）
- 配置不生效：确认修改的是对应 SAPI 的 php.ini 或已启用 xdebug.ini，并已重启 apache2/php-fpm
- 旧版 Xdebug 2 配置干扰：若看到 xdebug.remote_enable、xdebug.remote_port 等，说明是 Xdebug 2，建议迁移到 Xdebug 3 的 mode=debug、client_host、client_port 等新参数

最新问答