Ubuntu环境下phpstorm如何调试PHP代码

Ubuntu下使用 PhpStorm 调试 PHP 的完整步骤

一 环境准备

• 安装 PHP 与 Xdebug（CLI 与 FPM 建议一致，避免调试不一致）：
  • 更新索引并安装：sudo apt update & & sudo apt install php php-xdebug
• 确认 CLI 的 php.ini 路径（后面会用到）：php -i | grep ‘Configuration File’
• 若使用 Nginx + PHP-FPM，确保 FPM 正在运行：sudo systemctl status php*-fpm
• 在 PhpStorm 中确认已识别 PHP 解释器：File → Settings → Languages & Frameworks → PHP（应显示已发现的 CLI 解释器）

二 配置 Xdebug 3（Ubuntu 20.04+ 常见）

• 编辑 CLI 与 FPM 各自的 php.ini（路径形如：/etc/php/{ php_version} /cli/php.ini 与 /etc/php/{ php_version} /fpm/php.ini），在末尾添加或修改：

  [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
  

  • 说明：Xdebug 3 使用 client_host/client_port 与 start_with_request；如使用旧版 Xdebug 2，常见为 remote_enable/remote_host/remote_port 等参数，请勿混用两套配置。
• 重启服务使配置生效：
  • Apache：sudo systemctl restart apache2
  • Nginx + PHP-FPM：sudo systemctl restart php**{ php_version} **-fpm & & sudo systemctl restart nginx
• 可选验证：php -v 应能看到 Xdebug 字样；或创建 phpinfo.php 查看是否加载 Xdebug。

三 在 PhpStorm 中完成调试配置

• 配置 Servers：File → Settings → Languages & Frameworks → PHP → Servers → +，填写
  • Name：自定义（如：localhost）
  • Host：localhost（或你的域名/IP）
  • Port：80/443
  • Debugger：Xdebug
  • 路径映射（Path mappings）：将项目根目录映射到服务器根目录（如：/home/user/project → /var/www/html）
• 配置 Debug 端口：File → Settings → Languages & Frameworks → PHP → Debug，确保 Debug port 为 9003（与 xdebug.client_port 一致）
• 创建运行/调试配置：Run → Edit Configurations → + → PHP Web Page
  • Server：选择上一步的服务器
  • URL：如 http://localhost/index.php
  • 勾选 “Break at first line in PHP scripts”（可选，便于确认调试是否生效）
• 启动调试：点击工具栏的绿色虫子图标或 Run → Debug，访问对应 URL，命中断点后即可查看变量、调用栈与单步执行。

四 远程调试与常见问题

• 远程服务器场景（如本机运行 PhpStorm，调试虚拟机/容器/另一台主机上的 PHP）
  • 在远程服务器 php.ini 中设置：

    [xdebug]
    zend_extension=xdebug.so
    xdebug.mode=debug
    xdebug.client_host=你的本机IP（可从远程访问到）
    xdebug.client_port=9003
    xdebug.start_with_request=yes
    xdebug.idekey=PHPSTORM
    

  • 在 PhpStorm：Run → Start Listening for PHP Debug Connections；浏览器访问时在 URL 后附加参数：?XDEBUG_SESSION_START=PHPSTORM，或使用浏览器插件（如 Xdebug Helper）一键开启调试会话。
  • 如存在防火墙/安全组，请放行 9003 端口；Docker 场景需将 client_host 指向宿主机（常见为 host.docker.internal 或宿主机局域网 IP），并确保端口映射正确。
• 常见问题快速排查
  • 端口占用：lsof -i:9003 检查谁在占用；必要时更换端口并同步 php.ini 与 PhpStorm 设置。
  • 未命中断点：确认访问的是 FPM 处理的请求（非 CLI）；检查 Servers 的路径映射是否正确；确认 Debug port 一致；查看 PhpStorm 的 Event Log 是否有 “Incoming Connection” 提示。
  • Xdebug 版本混淆：Xdebug 2 与 3 配置项不同，建议统一升级到 3 并按上文配置；用 php -v 与 phpinfo() 双重确认加载的扩展与参数。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！