Sublime Text 无法直接调试 PHP，需通过 php-debug 插件监听 Xdebug 发送的 XML 协议实现；关键前提是 Xdebug 扩展在 CLI 和 Web 的 php.ini 中均正确配置并启用，且 path_mapping 路径映射准确、端口一致、浏览器触发调试会话。
Sublime Text 本身不支持 Xdebug 调试，所谓“关联 Xdebug”，只是让 Sublime 能配合外部调试器（如 php-debug 插件 + Xdebug CLI 配置）接收断点响应——但实际调试流程、变量查看、单步执行全部依赖 Xdebug 扩展和 Web 服务器联动，Sublime 只负责展示。
php -v 能运行，但 Xdebug 不加载
Xdebug 是 PHP 扩展，不是 Sublime 插件。很多用户以为装了插件就等于能调试，结果 phpinfo() 里根本看不到 Xdebug 模块。
- 运行
php --ini查看当前 CLI 加载的php.ini路径（注意：CLI 和 Web 的配置文件通常不同） - 在该
php.ini中确认已启用：zend_extension=xdebug.so ; macOS/Linux ; 或 zend_extension=php_xdebug.dll ; Windows
- 必须加上最低必要配置（Xdebug 3+）：
xdebug.mode=debug xdebug.start_with_request=yes xdebug.client_host=127.0.0.1 xdebug.client_port=9003
- 改完后重启 PHP CLI 进程（比如关掉终端重开），再运行
php -m | grep xdebug确认模块在列表中
如果只配了 Web 服务器（如 Apache/Nginx）的 php.ini，而没动 CLI 的，php -v 成功但 php -m 无 xdebug，Sublime 就永远收不到调试连接。
php-debug 插件安装后无法启动监听
php-debug 是 Sublime 上最常用的 Xdebug 前端插件，但它不自带调试协议实现，纯靠监听 9003 端口并解析 Xdebug 发来的 XML。
立即学习“PHP免费学习笔记（深入）”；
- 安装方式必须用 Package Control，不能手动丢进 Packages 文件夹（否则依赖缺失）
- 安装后需手动创建项目级配置：菜单栏
Project → Edit Project，在settings下加："php-debug": { "path_mapping": { "/var/www/html/": "${project_path}/" } } -
path_mapping是关键：Xdebug 发来的文件路径是服务器上的绝对路径（如/var/www/html/index.php），Sublime 必须知道它对应你本地哪个文件夹，否则断点全失效 - Windows 用户注意反斜杠转义问题，应写成
"C:\xampp\htdocs\": "${project_path}/"
没有 path_mapping，插件会静默失败——看起来“监听已启动”，但点击断点毫无反应。
浏览器访问触发不了断点，但 CLI 脚本可以
这是最常见的混淆点：php-debug 默认监听的是 Web 请求（通过浏览器访问触发 Xdebug），不是命令行脚本。
- CLI 脚本默认不触发 Xdebug（除非加
XDEBUG_CONFIG="idekey=SUBLEME"环境变量或用-d参数强制开启） - Web 调试必须满足三个条件同时成立：
- 浏览器装了 Xdebug Helper（Chrome/Firefox 插件），且已启用 debug 模式
- 当前页面 URL 带
?XDEBUG_SESSION_START=SUBLEME（或用插件一键触发） - PHP 的
xdebug.mode包含debug，且xdebug.start_with_request设为yes或trigger
如果只在终端跑 php index.php，即使 Xdebug 已加载，也不会连上 Sublime——因为 CLI 模式下 Xdebug 默认不连接 IDE。
php-debug 监听端口被占用或连不上
Xdebug 3 默认用 9003，但很多用户还按老教程配 9000，或系统已有其他服务占用了该端口。
- 检查端口是否空闲：
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows） - 若被占，统一改两处：
-
php.ini中改为xdebug.client_port=9004 -
php-debug项目配置中加"port": 9004
-
- Sublime 启动监听后，底部状态栏应显示
PHP Debug: listening on 127.0.0.1:9003；若显示failed to bind，就是端口冲突或权限问题（macOS 可能需全盘访问权限）
Xdebug 调试链路长、环节多，任意一环断开（PHP 扩展未加载、端口不一致、路径映射错、浏览器未触发 session、CLI/Web ini 混用），都会表现为“点了断点没反应”。别猜，逐项验证 php -m、php --ini、lsof、浏览器插件开关状态。
