Debian系统phpstorm如何远程调试

Debian 上 PhpStorm 远程调试 PHP 的完整步骤

一 环境准备与版本选择

• 在 Debian 服务器安装与 PHP 版本匹配的 Xdebug 3.x（建议通过 apt 安装与你 PHP 版本一致的包，如 php-xdebug），并确保 CLI 与 FPM/Apache 使用的都是同一套 php.ini。
• 在本地机器安装并打开 PhpStorm，准备通过 Xdebug 的 DBGp 协议进行连接。
• 明确网络关系：
  • 同网段直连：服务器可直接访问你的本机 IP。
  • 跨网段/NAT：使用 SSH 隧道 转发调试端口。
• 建议统一调试端口为 9003（Xdebug 3 默认），便于与 PhpStorm 保持一致。

二 在 Debian 服务器安装并配置 Xdebug

• 安装扩展（以 Debian 11/12 为例，PHP 8.1/8.2 常见）：

  sudo apt-get update
  sudo apt-get install php-xdebug
  

• 编辑 Xdebug 配置（推荐修改版本目录下的模块配置，如：/etc/php/8.2/apache2/conf.d/20-xdebug.ini 或 /etc/php/8.2/fpm/conf.d/20-xdebug.ini）：

  zend_extension=xdebug.so
  xdebug.mode=debug
  xdebug.client_host=YOUR_PHPSTORM_HOST_IP    ; 你的 PhpStorm 所在机器的可达 IP
  xdebug.client_port=9003
  xdebug.start_with_request=yes            ; 每次请求都尝试连接调试器（也可用 trigger）
  ; 可选：便于识别会话
  xdebug.idekey=PHPSTORM
  

  说明：
  • 若服务器与 PhpStorm 不在同一网段，将 client_host 设为 127.0.0.1，并通过 SSH 隧道转发。
  • 若希望按需触发调试，可改为 xdebug.start_with_request=trigger 并在请求中携带触发参数。
• 使配置生效：

  # Apache
  sudo systemctl restart apache2
  # 或 PHP-FPM
  sudo systemctl restart php8.2-fpm
  # Nginx 搭配 FPM 时通常也需要重启 php-fpm
  sudo systemctl restart nginx
  

• 验证安装与参数：

  php -v | grep -i xdebug
  php -i | grep -E 'xdebug.mode|xdebug.client_host|xdebug.client_port|xdebug.idekey'
  

  看到 Xdebug 已启用且参数正确即可。

三 在 PhpStorm 中配置远程调试

• 设置 CLI 解释器：File → Settings → Languages & Frameworks → PHP → CLI Interpreter → 新增/选择远程或本机 PHP（用于代码智能与 CLI 调试）。
• 配置调试端口：File → Settings → Languages & Frameworks → PHP → Debug → Debug port 设为 9003（与 xdebug.client_port 一致）。
• 配置 Servers（用于 Web 调试映射）：File → Settings → Languages & Frameworks → PHP → Servers → 新建
  • Name：自定义
  • Host：你的站点域名或服务器 IP
  • Port：站点端口（如 80/443）
  • Debugger：选择 Xdebug
  • 路径映射：将服务器上的项目根目录映射到本机项目根目录（Deployment/本地代码同步后自动识别更佳）。
• 可选 DBGp Proxy：File → Settings → PHP → Debug → DBGp Proxy
  • IDE key：PHPSTORM（与 xdebug.idekey 一致）
  • Host：你的服务器 IP（或本地隧道映射后的地址）
  • Port：9003
• 启动监听：点击工具栏电话图标（Start Listening for PHP Debug Connections），保持监听状态。

四 触发调试与常见问题排查

• 触发方式
  • 自动触发：已设置 xdebug.start_with_request=yes 时，直接访问页面即可进入断点。
  • 手动触发：将 xdebug.start_with_request=trigger，在 URL 附加参数：

    http://your-domain/test.php?XDEBUG_SESSION_START=PHPSTORM
    

    或在浏览器安装 Xdebug helper 扩展并设置为 IDE key PHPSTORM。
• 常见问题
  • 端口不通：
    • 直连场景：确保服务器可访问你的本机 IP 与 9003 端口（云服务器需放行安全组/防火墙）。
    • NAT/跨网段：建立 SSH 隧道，例如：

      # 本地端口 9003 -> 服务器 9003
      ssh -R 9003:127.0.0.1:9003 user@your-server
      

      并在服务器 xdebug.ini 中保持 xdebug.client_host=127.0.0.1。
  • 端口被占用：

    sudo ss -lntp | grep 9003
    # 更换 xdebug.client_port 与 PhpStorm Debug port 为未占用端口（如 9004）
    

  • 断点未命中：
    • 核对 PhpStorm 的 Servers 路径映射是否正确（服务器路径 ↔ 本地路径）。
    • 确认请求确实经过已加载 Xdebug 的 FPM/Apache 进程。
    • 查看 Xdebug 日志定位握手失败原因（在 php.ini 设置 xdebug.log=/var/log/php-xdebug.log 后重启服务）。
  • 版本/扩展不匹配：
    • 使用 php -v 与 php -i | grep xdebug 确认 Xdebug 已加载且版本为 3.x；若不匹配，重新安装对应版本。

五 安全建议

• 仅在受控网络或临时调试时开启远程调试；生产环境建议保持 xdebug.start_with_request=trigger 并限制来源 IP。
• 使用 SSH 隧道 转发调试端口，避免将 9003 暴露到公网。
• 调试完成后及时关闭监听，并恢复更严格的 Xdebug/防火墙配置。