phpstorm在Debian上如何调试

在 Debian 上使用 PhpStorm 调试的完整步骤

一 环境准备

• 确认 PHP 版本 与 Web 服务（Apache/Nginx+PHP-FPM）工作正常，命令行执行 php -v 可查看版本。
• 安装 Xdebug（与 PHP 版本匹配）。
• 在 PhpStorm 中设置 CLI Interpreter 指向 Debian 上的 PHP 可执行文件，确保解释器可被正确识别。
• 如通过浏览器触发调试，建议安装浏览器 Xdebug Helper 扩展，便于一键开启调试会话。

二 安装与配置 Xdebug 3（推荐）

• 安装扩展（Debian 常见路径，按 PHP 版本选择，如 8.2/8.3）：
  • Debian 12/Bookworm 通常可直接安装：sudo apt-get install php-xdebug
  • 若版本库中无对应版本，可使用 PECL 安装并与当前 PHP 严格匹配版本。
• 编辑 Xdebug 配置（建议统一写到 /etc/php/8.x/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.idekey=PHPSTORM
    

  • 远程服务器调试（服务器需要连接你的 IDE 主机 IP）：

    zend_extension=xdebug.so
    xdebug.mode=debug
    xdebug.client_host=<你的IDE主机IP>
    xdebug.client_port=9003
    xdebug.start_with_request=yes
    xdebug.idekey=PHPSTORM
    

• 使配置生效：
  • Apache：sudo systemctl restart apache2
  • PHP-FPM：sudo systemctl restart php8.x-fpm（将 8.x 替换为实际版本）
• 说明：Xdebug 3 使用 xdebug.mode=debug 与 client_host/client_port 与 IDE 通信，默认端口为 9003。

三 PhpStorm 调试配置

• 设置 CLI 解释器：File > Settings > Languages & Frameworks > PHP > CLI Interpreter，选择或添加 Debian 上的 PHP 可执行文件。
• 配置调试端口：File > Settings > Languages & Frameworks > PHP > Debug，将 Debug port 设为 9003（与 xdebug.client_port 一致）。
• 配置服务器（用于 Web 调试）：File > Settings > Languages & Frameworks > PHP > Servers，新增服务器，填写 Name/Host/Port，将 Debugger 设为 Xdebug；若使用路径映射（例如容器/远程项目），在 Mappings 中设置本地项目路径与服务器路径对应关系。
• 浏览器触发（可选）：安装 Xdebug Helper，在扩展选项中将 IDE Key 设为 PHPSTORM，访问页面前开启调试即可自动连接。

四 开始调试

• Web 调试：在 PhpStorm 点击工具栏的 Start Listening for PHP Debug Connections（绿色电话图标），在浏览器访问对应 URL，命中断点后 IDE 会进入调试视图（变量、堆栈、单步等）。
• CLI 脚本调试：在 PhpStorm 中 Run > Edit Configurations，新建 PHP Script 或 PHP Remote Debug 配置，选择 CLI Interpreter，必要时设置 IDE Key；在代码中设置断点后点击调试运行，脚本会在断点处暂停。

五 常见问题与排查

• 端口不通：确认 xdebug.client_port=9003 与 PhpStorm 一致；服务器与 IDE 主机之间的 防火墙/安全组 放行 9003/TCP；远程调试时 xdebug.client_host 必须是 IDE 主机可达的 IP。
• 断点不生效：确认 Xdebug 已加载（php -m | grep xdebug），xdebug.mode=debug 已设置，且 PhpStorm 处于 监听 状态；Web 调试需确保请求携带正确的 IDE Key（如使用 Xdebug Helper）。
• 版本不匹配：Xdebug 2 与 Xdebug 3 配置项差异较大（如 remote_enable 属于 Xdebug 2）；请确认扩展版本与配置一致。
• 路径映射错误：CLI 一般无需映射；Web 项目在 Servers > Mappings 中校正本地与服务器路径，否则断点可能显示为未绑定。
• 服务未重启：修改 xdebug.ini 后需重启 Apache 或 PHP-FPM 才会生效。