linux中phpstorm如何配置xdebug

Linux下 PhpStorm 配置 Xdebug 实战指南

一 环境准备与版本选择

• 确认 PHP 版本，并选择匹配的 Xdebug 版本：
  • PHP 7.x/8.x：优先使用 Xdebug 3.x（配置项以 xdebug.mode、xdebug.client_host 等为主）。
  • PHP 5.6：使用 Xdebug 2.5.x（配置项以 xdebug.remote_enable、xdebug.remote_host 等为主）。
• 在 Linux 上安装 Xdebug 的常见方式：
  • 发行版包管理器安装（示例）：Ubuntu/Debian 可执行 sudo apt-get install php-xdebug；CentOS/RHEL 可执行 sudo yum install php-xdebug（或 dnf）。安装后仍需在 php.ini 中启用并配置 Xdebug。
  • PECL 安装：pecl install xdebug，记录安装输出的 .so 路径，后续在 php.ini 中用 zend_extension 加载。

二 在 Linux 上安装并启用 Xdebug

• 步骤概览：
  1. 查找 php.ini 位置：php --ini 或 find / -name “php.ini”；同时确认 CLI 与 FPM 是否各自有独立配置。
  2. 安装扩展（二选一）：
     • 发行版包管理器：sudo apt-get install php-xdebug 或 sudo yum install php-xdebug。
     • PECL：pecl install xdebug，记录 .so 路径（如：/usr/lib64/php/modules/xdebug.so）。
  3. 编辑 php.ini，按版本写入对应配置（见下一节示例）。
  4. 重启服务：sudo systemctl restart php-fpm 或 sudo systemctl restart apache2/nginx。
  5. 验证：php -m | grep xdebug 或 phpinfo() 应能看到 Xdebug 段落。

三 php.ini 关键配置示例

• Xdebug 3.x（PHP 7.x/8.x，推荐）
  • 基本调试（本机或容器同机调试常用 127.0.0.1）：

    [xdebug]
    zend_extension=/usr/lib64/php/modules/xdebug.so
    xdebug.mode=debug
    xdebug.client_host=127.0.0.1
    xdebug.client_port=9003
    xdebug.start_with_request=yes
    xdebug.idekey=PHPSTORM
    

  • 远程服务器/虚拟机调试（IDE 在物理机，Web 在虚拟机/服务器）：

    [xdebug]
    zend_extension=/usr/lib64/php/modules/xdebug.so
    xdebug.mode=debug
    xdebug.client_host=IDE机器的IP
    xdebug.client_port=9003
    xdebug.start_with_request=yes
    xdebug.idekey=PHPSTORM
    

    若网络环境复杂，可用 xdebug.discover_client_host=1 让 Xdebug 自动探测 IDE 主机（仅在可信网络中启用）。
• Xdebug 2.5.x（PHP 5.6 等老版本）

  [xdebug]
  zend_extension=/usr/lib64/php/modules/xdebug.so
  xdebug.remote_enable=1
  xdebug.remote_host=IDE机器的IP
  xdebug.remote_port=9001
  xdebug.remote_handler=dbgp
  xdebug.remote_autostart=1
  xdebug.idekey=PHPSTORM
  

• 端口与常见冲突
  • Xdebug 3 默认端口为 9003，Xdebug 2 常见为 9000/9001；若与 php-fpm 的 9000 端口冲突，建议将 Xdebug 改为 9003 或其他未占用端口，并在 PhpStorm 中保持一致。

四 在 PhpStorm 中完成调试配置

• 配置 Servers（路径映射）
  • File → Settings → Languages & Frameworks → PHP → Servers → +：
    • Name：自定义；Host：你的站点域名或服务器 IP；Port：80/443。
    • 勾选 Use path mappings，将本地项目根目录映射到服务器上的绝对路径（如：/var/www/html → /home/user/project）。
• 配置 Debug 端口
  • File → Settings → Languages & Frameworks → PHP → Debug：将 Debug port 设为与 php.ini 一致的端口（Xdebug 3 用 9003，Xdebug 2 用 9000/9001）。
• 创建运行/调试配置
  • Run → Edit Configurations → + → PHP Web Page（或 PHP Remote Debug）：
    • Server：选择上一步的服务器。
    • Start URL：调试起始页（如 /）。
    • IDE key：填写 PHPSTORM（与 php.ini 一致）。
• 启动调试
  • 点击工具栏的 电话听筒图标开启监听；在浏览器访问页面触发断点。
  • 触发方式（三选一，任选其一即可）：
    • 在 URL 后追加参数：?XDEBUG_SESSION_START=PHPSTORM
    • 使用浏览器 Xdebug 扩展一键开启调试会话
    • 配置 DBGp Proxy（Settings → PHP → Debug → DBGp Proxy：IDE key 填 PHPSTORM，Host 填 IDE 机器 IP，Port 填 9003）

五 常见问题排查

• 端口未监听或被占用
  • 确认 php.ini 的 xdebug.client_port/xdebug.remote_port 与 PhpStorm 的 Debug port 一致；用 ss -lntp | grep 9003 或 netstat -tulpen | grep 9003 检查占用；若与 php-fpm 冲突，将 Xdebug 改为 9003。
• 无法连接到 IDE
  • 远程场景需保证 IDE 所在机器的 防火墙/安全组放行对应端口（如 9003）；Xdebug 2 可用 xdebug.remote_connect_back=1 自动回连，但仅建议在可信网络使用；Xdebug 3 可用 xdebug.discover_client_host=1 自动探测。
• 断点不生效或找不到文件
  • 检查 Servers 中的 路径映射是否正确（本地路径 ↔ 服务器绝对路径）；确保访问的是配置了 Xdebug 的 同一服务器/端口；确认 Web 服务（Apache/Nginx/PHP-FPM）已重启并加载了 Xdebug。
• 扩展未生效
  • 确认 php.ini 中使用了 zend_extension=…xdebug.so（不是 extension=）；执行 php -m | grep xdebug 或 phpinfo() 验证；若使用多 SAPI（CLI/FPM/Apache），确保对应 ini 均已配置并重启对应服务。