linux上phpstorm如何配置Xdebug

Linux 上 PhpStorm 配置 Xdebug 实战指南

一 环境准备与版本选择

• 确认 PHP 版本：执行命令查看版本与 SAPI（如 php -v、php -m | grep -E ‘fpm|apache2’）。
• 选择 Xdebug 版本：
  • PHP 7.2–8.2：优先使用 Xdebug 3.x（默认端口 9003，配置项以 xdebug.mode=debug 为核心）。
  • PHP 5.6–7.1：使用 Xdebug 2.9（常见端口 9000/9001，配置项以 xdebug.remote_enable=1 为核心）。
• 安装方式二选一：
  • 发行版包管理器（Debian/Ubuntu）：如 sudo apt-get install php-xdebug 或 sudo apt-get install php7.x-xdebug。
  • PECL：sudo pecl install xdebug（会自动匹配适合的版本）。安装后在 php.ini 中加载扩展。

二 安装与配置 Xdebug

• 编辑正确的 php.ini（注意 CLI 与 FPM/Apache 可能不同）：
  • 常见路径：/etc/php/{version}/{cli|fpm|apache2}/php.ini。
• 推荐配置（按版本区分，二选一）：
  • Xdebug 3（PHP 7.2+，推荐）

    zend_extension=xdebug.so
    xdebug.mode=debug
    xdebug.client_host=127.0.0.1
    xdebug.client_port=9003
    xdebug.start_with_request=yes
    ; 可选：日志便于排错
    ; xdebug.log=/tmp/xdebug.log
    

  • Xdebug 2（PHP 5.6–7.1）

    zend_extension=xdebug.so
    xdebug.remote_enable=1
    xdebug.remote_handler=dbgp
    xdebug.remote_mode=req
    xdebug.remote_port=9001
    xdebug.remote_connect_back=1
    xdebug.idekey=PHPSTORM
    ; 可选：日志便于排错
    ; xdebug.remote_log=/tmp/xdebug.log
    

• 重启服务使配置生效：
  • PHP-FPM：sudo systemctl restart php{version}-fpm
  • Apache：sudo systemctl restart apache2
  • Nginx（配合 PHP-FPM）：sudo systemctl restart nginx
• 验证安装：
  • 执行 php -v，应看到 with Xdebug 字样。
  • 临时创建 info.php 输出 phpinfo();，访问页面确认 Xdebug 模块已加载。

三 PhpStorm 调试配置

• 设置 PHP 解释器：
  • File → Settings → Languages & Frameworks → PHP → CLI Interpreter，选择或添加本机 PHP 可执行文件（远程项目可添加远程解释器）。
• 配置 Debug 端口：
  • File → Settings → Languages & Frameworks → PHP → Debug：将 Xdebug Port 设为与 php.ini 一致的 9003（Xdebug 3） 或 9001（Xdebug 2）。
• 配置 DBGp Proxy（Xdebug 2 常用）：
  • File → Settings → Languages & Frameworks → PHP → Debug → DBGp Proxy：
    • IDE key：PHPSTORM
    • Host：本机 IP
    • Port：与 xdebug.remote_port 一致（如 9001）
• 配置 Servers（远程调试关键）：
  • File → Settings → Languages & Frameworks → PHP → Servers → +：
    • Name：自定义；Host：目标站点域名或 服务器IP；Port：80/443
    • Debugger 选 Xdebug
    • 勾选 Use path mappings，设置本地项目根目录与服务器上代码的 绝对路径映射（远程调试必配，否则断点无法命中）
• 创建运行配置：
  • Run → Edit Configurations → + → PHP Web Application：
    • 选择上一步的 Server
    • 设置 Start URL（如 / 或具体入口）
• 启动调试：
  • 点击工具栏 Start Listening for PHP Debug Connections（电话图标），访问对应 URL 即可命中断点。

四 远程调试与网络连通

• 同网段场景：
  • 服务器可直接回连 IDE 主机 IP，Xdebug 2 可用 xdebug.remote_connect_back=1 自动识别来源；Xdebug 3 使用 xdebug.client_host=IDE_IP。
• 跨网段/公网场景（服务器在内网、IDE 在外网）：
  • 方案 A：SSH 隧道（推荐）
    • 命令示例：ssh -R 9003:localhost:9003 user@server（将服务器 9003 转发到本机 9003）
    • 服务器 php.ini：xdebug.client_host=127.0.0.1（隧道回连本机）
  • 方案 B：路由器端口映射（将公网端口映射到 IDE 主机）
• 防火墙与监听：
  • 确保 IDE 主机开放对应端口（如 9003/9001），并确认 PhpStorm 处于“监听”状态。

五 常见问题排查

• 端口冲突：
  • PHP-FPM 默认 9000，与 Xdebug 端口冲突。将 Xdebug 改为 9003（Xdebug 3）或 9001（Xdebug 2），并同步修改 PhpStorm 与 php.ini。
• 断点不命中：
  • 远程调试未启用 Use path mappings 或映射路径不正确；检查 Servers 配置与服务器绝对路径。
• 无法连接：
  • 核对 xdebug.client_port/remote_port 与 PhpStorm 端口一致；跨网段未做 SSH 隧道/端口映射；服务器防火墙未放行。
• 版本混淆：
  • Xdebug 2 与 3 配置项差异大，请按 PHP 版本使用对应配置；不确定时查看 phpinfo 或 php -v 输出确认 Xdebug 版本。