phpstorm在Debian如何进行调试

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

一 前置准备

• 确认已安装 PHP（含 CLI 与 Web 模块，如 apache2/php-fpm），版本建议 7.4+。执行 php -v 查看版本。
• 确认 PhpStorm 已安装并打开项目。
• 选择调试引擎为 Xdebug 3.x（推荐），下文均以此为准。

二 安装与配置 Xdebug

• 安装扩展（推荐包管理器）：
  • 执行：sudo apt update && sudo apt install php-xdebug
• 编辑对应 php.ini（按运行模式区分）：
  • CLI：/etc/php/<version>/cli/php.ini
  • Apache：/etc/php/<version>/apache2/php.ini
  • PHP-FPM：/etc/php/<version>/fpm/php.ini
• 写入以下关键配置（将 替换为实际版本，如 8.2）：

  [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
  

  • 手动编译安装时，zend_extension 需写绝对路径（如：/usr/lib/php/20220829/xdebug.so）。
• 使配置生效：
  • Apache：sudo systemctl restart apache2
  • PHP-FPM：sudo systemctl restart php<version>-fpm

三 PhpStorm 端配置

• 设置 CLI 解释器：File → Settings → Languages & Frameworks → PHP → CLI Interpreter → Add → Local，选择 PHP 可执行文件（如 /usr/bin/php）。
• 配置 Debug：File → Settings → Languages & Frameworks → PHP → Debug
  • Debug port：9003（与 xdebug.client_port 一致）
  • 勾选 Xdebug，IDE key 为 PHPSTORM
• 配置 Servers：File → Settings → Languages & Frameworks → PHP → Servers → +
  • Name：自定义（如 Debian_Local）
  • Host：127.0.0.1（本地）或服务器 IP（远程）
  • Port：80/443
  • 勾选 Use path mappings，将本地项目路径映射到服务器路径（如：/home/user/project → /var/www/html）

四 开始调试

• 本地 Web 调试
  • 在代码行号左侧点击设置断点。
  • 点击工具栏电话图标（Start Listening for PHP Debug Connections）或按 Shift+F9。
  • 浏览器访问项目 URL（如 http://localhost），命中断点后可在 PhpStorm 查看变量、调用栈、控制台等。
• 远程服务器调试
  • 服务器端 xdebug.client_host 需设为 PhpStorm 所在机器的 IP。
  • 在 PhpStorm 使用 远程解释器（SSH Interpreter）或 Deployment（SFTP）+ 路径映射。
  • 启动监听后，浏览器访问时在 URL 后附加参数：?XDEBUG_SESSION=PHPSTORM，或使用 Xdebug Helper 插件一键开启。
  • 确保服务器防火墙放行 9003 端口（或建立 SSH 隧道 转发 9003）。

五 常见问题排查

• Xdebug 未加载：执行 php -m | grep xdebug，若无输出，检查 zend_extension 路径与 php.ini 是否生效。
• 端口冲突：若 9003 被占用，修改 xdebug.client_port（如 9004）并同步 PhpStorm 的 Debug port。
• 路径映射错误：确保 Servers → Path mappings 正确，否则断点无法命中或变量不可读。
• 远程连不通：核对 xdebug.client_host 为 IDE 机器 IP，并开放 9003 端口或配置 SSH 隧道。

附 旧版 Xdebug 2 配置提示

• 若使用 Xdebug 2.x，常见配置为：

  zend_extension=xdebug.so
  xdebug.remote_enable=1
  xdebug.remote_host=127.0.0.1
  xdebug.remote_port=9003
  xdebug.remote_autostart=1
  xdebug.remote_connect_back=1
  

• 新版（3.x）已统一为 xdebug.mode=debug、xdebug.client_host、xdebug.client_port 等参数，优先使用 3.x 配置。