Sublime Text 3配置Xdebug调试教程

本文详细讲解了在 Sublime Text 3 中配置 Xdebug 3.x 进行 PHP 调试的完整、可靠方案，强调必须使用现代 Debugger 插件（基于 DAP 协议）替代已淘汰的 SublimeXdebug，并系统梳理了关键配置要点：确保 Xdebug 模块正确加载、启用 `xdebug.mode=debug`、开放并验证 9003 端口、精准设置 `pathMappings` 映射路径、通过浏览器插件触发带调试参数的请求，以及从终端启动 Sublime 以加载正确的 php.ini；同时指出 Sublime 本身不支持原生 PHP 调试，其角色仅为被动接收端，真正调试能力完全依赖 Xdebug 的主动连接与日志诊断，为开发者提供了一套经实践验证、兼容 PHP 8.2+ 和 Xdebug 3.x 的高效调试落地指南。

Sublime Text 3 本身不支持原生 PHP 调试，必须靠插件 + 外部 Xdebug 扩展协同工作；当前最可行的方案是用 Debugger 插件（DAP 协议），SublimeXdebug 已基本淘汰，对 Xdebug 3.x 支持极差，容易断点失效、变量为空。

确认 Xdebug 已加载且监听正确端口

Sublime 只是“被动接收方”，Xdebug 必须主动连进来。如果 phpinfo() 页面里没看到 Xdebug 模块，或 php -m | grep xdebug 无输出，后续所有配置都无效。

• Xdebug 3.x 必须设 xdebug.mode=debug，旧配置如 xdebug.remote_enable=1 会被忽略
• xdebug.client_port 默认是 9003（不是 9000），改了就得同步改插件配置
• Windows 用户务必检查防火墙是否放行 9003 端口；macOS/Linux 可用 telnet 127.0.0.1 9003 测试端口是否可被 PHP 进程访问
• 加一行 xdebug.log="/tmp/xdebug.log"（路径需有写权限），出问题时直接看日志比猜快得多

用 Debugger 插件替代 SublimeXdebug

SublimeXdebug 自 2022 年起停止维护，不支持 super_globals、pathMappings 多映射、异步请求，且无法识别 $_SERVER 等关键变量。截至 2026 年，Debugger 是唯一稳定支持 Xdebug 3.x 和 PHP 8.2+ 的方案。

• 通过 Package Control 安装 Debugger（不是 SublimeXdebug）
• 菜单栏 → Tools → Debugger → Open Launch Configurations，选 PHP 模板生成基础配置
• 关键字段必须填对："pathMappings" 左侧是 PHP 实际运行路径（如 /var/www/html/ 或 Docker 容器内路径），右侧是 Sublime 项目根目录（可用 ${folder}）
• 保存后状态栏右下角应显示 Debugger: PHP，没出现说明配置未加载

浏览器触发调试会话的三个硬性条件

Debugger 不会主动发起连接，必须由一次带调试标识的 HTTP 请求“唤醒”Xdebug，再由它反向连回 Sublime。缺一不可。

• PHP 文件开头必须有 ，否则 Xdebug 直接跳过整个文件，Sublime 静默无反应
• 浏览器必须安装 Xdebug Helper（Chrome/Firefox 均可），IDE key 设为 sublime.xdebug，并手动点击虫子图标启用（仅安装不启用 = 无效）
• 访问 URL 必须带 ?XDEBUG_SESSION_START=sublime.xdebug 参数，或依赖插件自动注入；只打开 index.php 不加参数 = 不触发
• 断点必须是红色实心圆点（灰色 = 未识别），点击行号左侧空白处设置；断点在 if、for 等控制结构第一行常不生效，建议设在内部语句上

常见静默失败：Sublime 启动时没读到你的环境