如何在Ubuntu用phpstorm调试代码

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

一 环境准备

• 安装 PHP 与 Web 服务（Apache 或 Nginx + PHP-FPM），并确认 CLI 与 FPM 使用的 PHP 版本一致（如 7.4/8.0/8.1/8.2/8.3）。
• 安装 Xdebug 扩展（与 PHP 版本匹配）：
  • Ubuntu/Debian 系可直接安装发行版包：sudo apt-get install php-xdebug。安装完成后可用 php -v 或 php -m | grep xdebug 验证是否加载成功。

二 配置 Xdebug 3（Ubuntu 20.04+ 与 PHP 8 推荐）

• 找到正确的 ini 文件位置（按实际版本替换 {php_version}）：
  • CLI：/etc/php/{php_version}/cli/php.ini
  • FPM：/etc/php/{php_version}/fpm/php.ini
  • Apache：/etc/php/{php_version}/apache2/php.ini
• 在对应 ini 的末尾添加或修改（Xdebug 3 常用配置）：

  [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
  

  • 说明：client_port 默认 9003；如与 php-fpm 冲突，可改为 9000/9100 等未占用端口。
• 重启服务使配置生效：
  • sudo systemctl restart php{php_version}-fpm
  • sudo systemctl restart apache2 或 sudo systemctl restart nginx。

三 配置 PhpStorm

• 设置 PHP 解释器：File → Settings → Languages & Frameworks → PHP → CLI Interpreter，选择或添加 /usr/bin/php。
• 配置服务器与调试端口：
  • Servers：Languages & Frameworks → PHP → Servers → +，填写 Name、Host（如 localhost）、Port（如 80/443），Debugger 选 Xdebug；本地开发一般无需路径映射。
  • Debug：Languages & Frameworks → PHP → Debug，将 Debug port 设为与 xdebug.client_port 一致（默认 9003）。
• 创建运行配置：Run → Edit Configurations → + → PHP Web Page，选择刚才的 Server，配置 Start URL（如 /index.php）。

四 开始调试

• 在代码行号左侧单击设置断点；在 PhpStorm 工具栏点击“电话听筒”图标以开始监听调试连接（Run → Start Listening for PHP Debug Connections）。
• 触发调试：
  • 浏览器访问目标页面，附加调试会话：在 URL 后追加参数 ?XDEBUG_SESSION_START=PHPSTORM，如：
    • http://localhost:8080/index.php?XDEBUG_SESSION_START=PHPSTORM
  • 或使用浏览器扩展（如 Xdebug Helper）设置 IDE Key 为 PHPSTORM 后访问页面。命中断点后，PhpStorm 会弹出调试窗口，可使用 F7 单步进入、F8 单步跳过、Shift+F8 跳出 等控制执行，并查看变量与调用栈。

五 常见问题与排查

• 端口被占用：将 xdebug.client_port 与 PhpStorm 的 Debug port 改为 9000/9100 等未被占用的端口，并同步修改 php.ini 与 PhpStorm 设置。
• 监听未触发：确认已点击“电话听筒”开始监听，且访问 URL 包含 XDEBUG_SESSION_START=PHPSTORM 或浏览器扩展已启用。
• 配置未生效：核对修改的是实际生效的 FPM/Apache 的 php.ini，并重启对应服务；可用 phpinfo() 或 php -i | grep xdebug 检查 Xdebug 配置是否加载。
• 虚拟机/Vagrant/WSL 场景：需在 IDE 的 Deployment → Mappings 中配置本地与虚拟环境的目录映射，并确保端口转发正确。