Linux下使用 PHPStorm 调试代码的实用步骤
一 环境准备
- 安装并启动 PHPStorm（Linux 版），创建或打开项目。
- 安装 Xdebug 扩展（与 PHP 版本匹配）。例如在 Ubuntu/Debian：sudo apt-get install php-xdebug；在 CentOS/RHEL：sudo yum install php-xdebug。安装完成后可用 php -v 与 php -m | grep xdebug 验证是否加载成功。
二 本地 Web 调试步骤（同一台 Linux 机器）
- 配置 php.ini（Xdebug 3 常用写法，端口用 9003）：
- 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
保存后重启 Apache 或 PHP-FPM：sudo systemctl restart apache2 或 sudo systemctl restart php-fpm。
- 配置 PHPStorm：
- 设置解释器：File → Settings → Languages & Frameworks → PHP → CLI Interpreter，选择 PHP 可执行文件（如 /usr/bin/php）。
- 配置调试端口：File → Settings → PHP → Debug，确保 Debug port 为 9003。
- 新建运行配置：Run → Edit Configurations → + → PHP Web Page，选择服务器与起始 URL。
- 开始调试：
- 在代码行号左侧单击设置断点。
- 点击工具栏电话图标“Start Listening for PHP Debug Connections”，或运行刚创建的调试配置。
- 浏览器访问目标页面，例如：http://localhost/your-app/index.php?XDEBUG_SESSION_START=PHPSTORM，命中断点后即可单步、查看变量与调用栈。
三 远程服务器调试步骤（服务器在 Linux，IDE 在本地或其他机器）
- 服务器（如 CentOS/Ubuntu）配置 php.ini（Xdebug 3）：
- zend_extension=xdebug.so
- xdebug.mode=debug
- xdebug.client_host=你的IDE机器IP（如 192.168.1.100）
- xdebug.client_port=9003
- xdebug.start_with_request=yes
- xdebug.idekey=PHPSTORM
保存后重启 Apache/Nginx 或 PHP-FPM。
- PHPStorm 配置：
- Servers：File → Settings → PHP → Servers → +，填写服务器 Host/Port，勾选 Use path mappings，将本地项目路径映射到服务器代码路径（容器/远程路径需一一对应）。
- 调试配置：Run → Edit Configurations → + → PHP Remote Debug，选择上一步的 Server，IDE key 填 PHPSTORM。
- 启动与触发：
- 在 PHPStorm 中点击“Start Listening for PHP Debug Connections”。
- 浏览器访问远程站点并在 URL 中携带会话标识：http://your-server/your-app/index.php?XDEBUG_SESSION_START=PHPSTORM，命中断点即可调试。
- 网络与安全：确保服务器防火墙/安全组放行 9003 端口，且 IDE 机器的 IP 可被服务器访问；如使用 Docker，需保证容器网络与端口映射正确。
四 常见问题与快速排查
- 端口未连通或被占用：确认 php.ini 的 xdebug.client_port 与 PHPStorm 的 Debug port 一致（默认 9003），并用 netstat -tulpen | grep 9003 检查监听；必要时更换端口并同步两边配置。
- 断点未命中：核对 Servers 的 path mappings 是否正确；远程场景确认 xdebug.client_host 指向 IDE 机器 IP；必要时在 URL 中添加 XDEBUG_SESSION_START=PHPSTORM 触发调试会话。
- 配置不生效：修改 php.ini 后需重启 Apache/Nginx/PHP-FPM；不同 SAPI（CLI/FPM）可能读取不同 ini 文件，建议同时检查 /etc/php/…/cli/php.ini 与 /etc/php/…/fpm/php.ini 或 /etc/php.ini。