Sublime Text 需通过 SublimeXdebug 插件实现 Xdebug 调试，仅支持 ST3 和 Xdebug 2.x（对 3.x 支持有限），依赖正确配置 php.ini（如 xdebug.mode=debug、xdebug.client_host、path_mapping 映射等），并需浏览器带 XDEBUG_SESSION_START 参数触发连接。
Sublime Text 本身不原生支持 Xdebug 调试，但可通过 SublimeXdebug 插件（非官方、社区维护）实现基础断点调试能力。它依赖外部 PHP 环境中的 Xdebug 扩展正常工作，且仅支持 Xdebug 2.x（XDEBUG_CONFIG 协议），对 Xdebug 3.x 的 debug 协议支持非常有限或需手动降级适配。
确认 Xdebug 已正确启用并监听请求
这是最关键的前置条件。SublimeXdebug 不会启动调试器，只被动接收 Xdebug 发来的连接。必须确保：
-
xdebug.mode在php.ini中设为debug（Xdebug 3.x）或xdebug.remote_enable=1（Xdebug 2.x） -
xdebug.start_with_request设为yes或trigger（推荐用trigger避免全站拦截） -
xdebug.client_host指向你的开发机 IP（如127.0.0.1），xdebug.client_port默认是9003（Xdebug 3.x）或9000（Xdebug 2.x） - 重启 Web 服务（如 Apache/Nginx）和 PHP-FPM（如使用）
- 访问
phpinfo()页面，搜索xdebug，确认模块已加载且配置值与预期一致
常见错误现象：SublimeXdebug 状态栏长期显示 “waiting for xdebug…” 但无响应 —— 大概率是 Xdebug 根本没连上来，先检查 phpinfo() 和日志（xdebug.log 路径需显式配置）。
安装 SublimeXdebug 并配置端口与路径映射
该插件已多年未更新，仅兼容 Sublime Text 3（ST3），不支持 ST4。安装后需手动编辑其设置：
立即学习“PHP免费学习笔记（深入）”；
- 通过
Package Control → Install Package → SublimeXdebug安装 - 打开
Preferences → Package Settings → SublimeXdebug → Settings - 关键字段必须匹配你的环境：
{
"url": "http://localhost",
"path_mapping": {
"/var/www/html/": "/Users/you/project/"
},
"port": 9003,
"ide_key": "sublime.xdebug"
}
path_mapping 是核心：左侧是服务器上 PHP 文件的绝对路径（如 Docker 容器内路径或远程服务器路径），右侧是本地 Sublime 打开的项目路径。若不匹配，断点会“命中但不触发”或变量显示为 undefined。
在浏览器中触发调试会话
SublimeXdebug 不主动发起连接，必须靠浏览器（或 curl）带特定参数请求，让 Xdebug 主动反向连接 Sublime：
- 手动加参数：
http://localhost/script.php?XDEBUG_SESSION_START=sublime.xdebug - 或安装浏览器插件（如 Chrome 的
Xdebug Helper），将 IDE key 设为sublime.xdebug后点击虫子图标 - 确保 Sublime 中已打开对应
.php文件，并在行号左侧单击设断点（出现红点） - 刷新页面后，Sublime 状态栏应变为 “connected”，光标停在断点行
注意：Xdebug 3.x 默认关闭 xdebug.start_with_request，必须显式传参或配合 Xdebug Helper 插件；若用 CLI 调试（php script.php），需额外设置环境变量：XDEBUG_MODE=debug php script.php，且 Sublime 必须提前监听。
常见断点失效与变量无法查看的原因
不是插件坏了，大概率是路径或协议错位：
- 断点红点显示但不中断 →
path_mapping键值颠倒，或服务器路径写成了相对路径 - 中断后变量窗为空或报
unable to evaluate expression→ Xdebug 版本 > 2.9 且未降级到 2.x，或xdebug.overload_var_dump=Off未设置（影响变量展开） - 频繁断连 →
sublime.xdebug的ide_key与 URL 参数 / 浏览器插件设置不一致 - 中文路径乱码 → SublimeXdebug 不处理编码转换，避免在路径中使用中文
真正麻烦的从来不是“怎么配”，而是当 Xdebug 3.x + ST3 + SublimeXdebug 这个组合里任意一环版本越界，整个链路就静默失败 —— 它不会报错，只会等，然后你开始怀疑人生。
