如何在Linux服务器上开启Xdebug远程调试功能的详细步骤-php教程-PHP中文网

xdebug配置成功的关键在于xdebug连得上谁、谁在监听、路径对不对三者一致；需确认cli与web模式加载的php.ini路径不同，区分xdebug 2.x与3.x参数差异，验证扩展是否真实加载并确保网络通路双向通畅。

如何在linux服务器上开启xdebug远程调试功能的详细步骤

能开启，但关键不在“装没装”，而在「Xdebug连得上谁、谁在监听、路径对不对」——三者错一个，xdebug.remote_enable=1 就是摆设。

确认 PHP 实际加载的 php.ini 路径

CLI 和 Web（如 php-fpm）用的不是同一个 php.ini。很多人改了 CLI 的配置，却忘了 php-fpm 根本不读它。

执行 php --ini 查 CLI 加载路径
执行 php-fpm -t && kill -USR2 $(cat /var/run/php-fpm.pid) 后访问 http://your-site.com/info.php（内容为 <?php phpinfo(); ?>），搜索 “Loaded Configuration File” 看 Web 模式真实路径
常见位置：/etc/php/8.2/fpm/php.ini、/usr/local/php/etc/php.ini、/opt/remi/php82/root/etc/php.ini —— 不要猜，必须查

配置 xdebug.so 路径和核心参数（注意版本差异）

Xdebug 3.x 和 2.x 参数名完全不同，混用会导致静默失效。Linux 上现在默认是 3.x（2026 年主流发行版已不再预装 2.x）。

Zynq Linux Hardware Debug

Zynq‑7000 / Zynq UltraScale+ 硬件调试技能。适用于 Xilinx Zynq（Cortex‑A9/A53 + FPGA）Linux 环境，调试 I2C、I2S、UART、GPIO 等外设。包括设备树配置、内核驱动、用户空间调试工具、交叉编译和常见问题排查，支持 PetaLinux 开发。

下载

先运行 php -v | grep -i xdebug 确认版本；若无输出，说明扩展未加载成功
Xdebug 3.x 必须用：
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=192.168.1.100（填你本地开发机的内网 IP）
xdebug.client_port=9003（PHPStorm 默认端口已是 9003，不是 9000）
Xdebug 2.x（已淘汰）用的是 xdebug.remote_enable 等旧键名，继续用会完全不生效
zend_extension 的值必须是绝对路径，比如 /usr/lib/php/20220829/xdebug.so；用 find /usr -name "xdebug.so" 2>/dev/null 找准位置

重启服务并验证是否真加载

改完配置不重启 = 白改；重启了没验证 = 不知道有没有生效。

如果是 php-fpm + Nginx：运行 sudo systemctl restart php-fpm nginx（或 sudo service php8.2-fpm restart && sudo systemctl reload nginx）
如果是 Apache：运行 sudo systemctl restart apache2
验证方式只有一种：php -m | grep xdebug（CLI 模式）+ curl http://localhost/info.php 2>/dev/null | grep -A5 -B5 "xdebug"（Web 模式）
如果 phpinfo() 页面里没有 Xdebug 区块，或显示 “disabled”，大概率是 zend_extension 路径错了，或被其他扩展（如 opcache）顺序干扰

防火墙和网络通路必须双向通畅

Xdebug 是从服务器「主动连出」到你的 IDE，不是 IDE 连入服务器 —— 所以重点不是服务器开什么端口，而是服务器能否访问你本地的 xdebug.client_host:xdebug.client_port。

在 Linux 服务器上执行：telnet 192.168.1.100 9003（替换成你本地 IP 和端口）。如果连接失败，说明网络不通或本地防火墙拦截
Linux 服务器本身一般无需开放 9003 入站端口；但如果你用 SSH 隧道（例如调试公网服务器），则需确保隧道命令中 -R 方向正确：ssh -R 9003:127.0.0.1:9003 user@local-ip，且本地 IDE 监听 127.0.0.1:9003
常见坑：xdebug.client_host 写成 localhost 或 127.0.0.1 —— 这会让服务器尝试连自己，而不是你的开发机

最常卡住的地方：你以为配好了，其实 php-fpm 没读那个 php.ini，或者 xdebug.client_host 指向了一个根本收不到包的地址。别信日志，直接 telnet 测通路，用 phpinfo() 看实际加载状态。其他都是次要的。