Sublime Text怎么实现远程调试_Sublime Text配合Xdebug步骤【后端】-sublime-PHP中文网

xdebug 远程调试失败主因是模块未启用或配置错误：需确认 php -m | grep xdebug 有输出，且 php --ri xdebug 显示 xdebug.mode = debug；xdebug.client_host 必须设为本地 ip（非 127.0.0.1），pathmappings 需正确映射远程与本地路径，url 中需带 ?xdebug_session_start=sublime.xdebug 参数，端口 9003 需在服务器及本地防火墙放行。

sublime text怎么实现远程调试_sublime text配合xdebug步骤【后端】

确认 Xdebug 是否在远程服务器上真正启用

Sublime Text 本身不参与调试逻辑，它只是被动接收 Xdebug 主动发起的连接。所以远程调试失败，90% 是卡在这一步：Xdebug 根本没连出来。

必须在远程服务器上执行 php -m | grep xdebug，有输出才说明模块已加载；再用 php --ri xdebug 看是否显示 xdebug.mode => debug —— 如果是 off 或报错，说明配置未生效。

常见错误现象：

phpinfo() 页面里没有 Xdebug 模块区块
日志路径（如 xdebug.log="/var/log/xdebug.log"）下无新文件生成
用 telnet 远程IP 9003 从本地能通，但从远程服务器 telnet 127.0.0.1 9003 却不通（说明 Xdebug 尝试连的是自己，不是 Sublime）

关键点：Xdebug 3.x 必须用 xdebug.mode=debug，xdebug.remote_enable=1 这类旧参数会被完全忽略；xdebug.client_host 要填你本地机器的公网/局域网 IP（比如 192.168.1.50），不能写 127.0.0.1（那是远程服务器自己）。

Sublime 的 Debugger 插件必须配对 pathMappings

远程调试时，Xdebug 发来的断点位置是服务器上的绝对路径（如 /var/www/html/index.php），而 Sublime 打开的是你本地的代码目录（如 /Users/me/project）。两者不匹配，断点就变灰色，点击无效。

配置方式（通过 Tools → Debugger → Open Launch Configurations）：

"pathMappings" 是对象，不是数组；左边是远程路径，右边是本地路径
Windows 用户注意反斜杠要双写："C:\\www\\project"
Docker 或 WSL 场景下，“远程路径”指容器内路径，不是宿主机路径
路径末尾不要加斜杠，"/var/www/html/" 和 "/var/www/html" 在某些版本中会不匹配

验证方法：启动监听后，在 Sublime 状态栏右下角看到 Debugger: PHP，且打开对应文件时行号左侧能点出红色实心圆点，才算映射成功。

Xdebug 3.4.1

Xdebug 3.4.1 是一款功能强大的 PHP 调试扩展工具，于 2025 年 1 月 6 日正式发布。作为 Xdebug 3.4 系列的首个修复版本，3.4.1 版在继承上一版本强大功能的同时，重点解决了稳定性问题。该版本不仅修复了访问超全局变量时可能引发的程序崩溃现象，还增强了对 Windows 平台 PIE 构建机制的支持，为广大 PHP 开发者提供了更加稳定的调试环境。这一版本适合所有

下载

浏览器访问必须触发 Xdebug 会话，不能只靠插件

即使装了 Xdebug Helper，也必须手动点击插件图标启用（虫子变绿色），否则它不会往请求头或 URL 注入 XDEBUG_SESSION_START 参数。

更可靠的做法是直接在 URL 后加参数访问，例如：

http://your-remote-domain.com/index.php?XDEBUG_SESSION_START=sublime.xdebug

注意：

sublime.xdebug 要和 Sublime 配置里的 "ide_key" 值一致（默认就是这个）
如果用了自定义 ide_key，URL 参数名也得跟着改，比如 ?XDEBUG_SESSION_START=mykey
PHP 文件开头必须有 <?php ，否则 Xdebug 直接跳过整文件，Sublime 完全静默

端口与防火墙是远程调试最常被忽略的环节

默认端口是 9003，但很多教程仍沿用旧版的 9000。Sublime 的 Debugger 插件默认监听 9003，如果你改了 Xdebug 的 xdebug.client_port，就必须同步改 Sublime 配置里的 "port" 字段。

远程服务器上务必检查三件事：

运行 ss -tuln | grep :9003，确认没有其他进程占着端口
防火墙是否放行该端口（ufw allow 9003 或 firewall-cmd --add-port=9003/tcp --permanent）
云服务器安全组（如阿里云、AWS）是否开放了入方向的 9003/TCP

本地机器如果开了防火墙（尤其是 Windows Defender 防火墙），也要确保允许入站连接到 9003 —— 不报错、不断点、不弹窗，只是“什么都没发生”，大概率就是这里被拦了。