phpstorm在Debian中如何配置Xdebug

在 Debian 中配置 PhpStorm 与 Xdebug 的完整步骤

一 准备与版本确认

• 确认 PHP 版本：运行命令查看版本与 SAPI（如 apache2、fpm）
  • 查看版本：php -v
  • 查看 SAPI：php -m | grep -E 'apache2|fpm'
• 安装对应版本的 Xdebug（示例为 PHP 8.2，请替换为你的实际版本）
  • sudo apt update
  • sudo apt install php8.2-xdebug
• 注意：不同 PHP 版本需安装对应的 php-xdebug 包，例如 php7.4-xdebug、php8.0-xdebug、php8.2-xdebug 等。

二 配置 Xdebug 3（Debian 常见默认）

• 编辑对应 SAPI 的 php.ini（常见路径，按你的版本与 SAPI 选择其一或多处）
  • Apache：/etc/php/8.2/apache2/php.ini
  • PHP-FPM（Nginx）：/etc/php/8.2/fpm/php.ini
  • CLI：/etc/php/8.2/cli/php.ini
• 在 php.ini 的末尾添加或修改如下配置（保持端口一致，推荐 9003）：

  [xdebug]
  zend_extension=xdebug.so
  xdebug.mode=debug
  xdebug.client_host=127.0.0.1
  xdebug.client_port=9003
  xdebug.start_with_request=yes
  xdebug.idekey=PHPSTORM
  

• 保存后重启服务
  • Apache：sudo systemctl restart apache2
  • PHP-FPM + Nginx：sudo systemctl restart php8.2-fpm && sudo systemctl restart nginx
  • CLI 无需重启，但请确保 CLI 与 Web 使用的是同一套 php.ini 配置（或分别配置）。

三 配置 PhpStorm

• 打开设置：File → Settings（macOS 为 Preferences）→ Languages & Frameworks → PHP → Debug
  • 将 Debug port 设为 9003（与 xdebug.client_port 一致）
• 配置 DBGp Proxy：Languages & Frameworks → PHP → Debug → DBGp Proxy
  • IDE key：PHPSTORM
  • Host：localhost
  • Port：9003
• 配置服务器：Languages & Frameworks → PHP → Servers
  • 点击 + 新建服务器
  • Name：自定义（如：localhost）
  • Host：localhost（或你的站点域名）
  • Port：80/443
  • Debugger：Xdebug
  • 勾选 Use path mappings，将项目本地路径映射到服务器路径（如部署在 /var/www/html 则映射为：本地项目根 → /var/www/html）
• 可选：CLI 解释器
  • Languages & Frameworks → PHP → CLI Interpreter → 选择或添加你的 PHP 可执行文件（如 /usr/bin/php8.2）。

四 启动调试与触发方式

• 在 PhpStorm 中开启监听：点击工具栏的 Start Listening for PHP Debug Connections（电话听筒图标）
• 触发调试的常用方式
  • 浏览器方式：安装并启用浏览器扩展（如 Xdebug Helper），选择 IDE Key 为 PHPSTORM，访问你的页面即可命中断点
  • 手动触发：在 URL 后追加参数 ?XDEBUG_SESSION_START=PHPSTORM，或在请求中携带 Cookie XDEBUG_SESSION=PHPSTORM
• 调试会话控制
  • 在代码行号左侧单击设置断点
  • 命中断点后使用 Step Over/Into/Out、查看 Variables/Call Stack
  • 继续执行：点击 Resume Program（F9）。

五 常见问题排查

• 端口被占用
  • 检查端口占用：sudo ss -lntp | grep 9003
  • 修改 php.ini 与 PhpStorm 的 client_port/Debug port 为未被占用的端口（如 9010），并同步更新
• 连接失败或无法命中断点
  • 确认 Web 与 CLI 使用的是同一套 php.ini（或分别正确配置）
  • 核对 PhpStorm 的 Servers → Path mappings 是否正确
  • 核对 DBGp Proxy 的 IDE key、Host、Port 与 php.ini 一致
  • 查看 Web 服务错误日志（Apache：/var/log/apache2/error.log；Nginx：/var/log/nginx/error.log）与 php-fpm 日志
• 远程/容器/虚拟机调试
  • 将 xdebug.client_host 设为 IDE 所在机器的 IP（如宿主机或开发机 IP），并确保网络可达
  • 若 IDE 与 Web 不在同一台机器，务必使用服务器的可达 IP，而非 127.0.0.1。