Sublime Text 调试 PHP 依赖 Xdebug 主动连接，90% 问题源于路径映射错误、端口不一致或 Xdebug 未启用；须确认 phpinfo() 和 php -m 显示 Xdebug 已加载，配置 xdebug.mode=debug，端口设为 9003，使用 Debugger 插件并正确设置 pathMappings。
Sublime Text 本身不跑 PHP，也不主动发起调试；它只是等 Xdebug 主动连上来。断点变灰、F5 没反应、变量不显示——90% 是路径没对齐、端口不一致或 Xdebug 根本没发连接。
确认 Xdebug 已加载且配置生效
这是所有后续操作的前提，跳过等于白配。
- 访问
phpinfo()页面，搜索Xdebug，必须看到模块信息和你写的配置项（如xdebug.mode值为debug） - 终端执行
php -m | grep xdebug，有输出才说明扩展已启用 - Xdebug 3.x 必须设
xdebug.mode=debug，xdebug.remote_enable=1这类旧配置会被完全忽略 - 端口默认是
9003，不是9000；如果改过xdebug.client_port，Sublime 的监听端口也得同步改 - 加一行
xdebug.log="/tmp/xdebug.log"（Linux/macOS）或xdebug.log="C:\xdebug.log"（Windows），出问题时直接看日志里有没有“connection failed”或“connecting to”
用 Debugger 插件而非 SublimeXdebug
截至 2026 年，Debugger 是唯一稳定支持 Xdebug 3.x + PHP 8.2+ + DAP 协议的插件。SublimeXdebug 只兼容 ST3 和 Xdebug 2.x，对 super_globals、多路径映射、异步请求支持极差。
- 通过 Package Control 安装
Debugger，别装SublimeXdebug - 安装后走
Tools → Debugger → Open Launch Configurations，选PHP模板生成配置，不要手写 - 配置中关键字段：
"type": "php"、"port": 9003、"pathMappings"必须严格匹配 - 状态栏右下角出现
Debugger: PHP才算配置加载成功；没出现说明 JSON 语法错或路径不对
pathMappings 左右两边必须严丝合缝
断点灰色 = Debugger 认为“这行代码根本不在运行路径里”。左边是 PHP 实际执行时看到的路径，右边是 Sublime 当前打开的项目根目录。
立即学习“PHP免费学习笔记（深入）”；
- 左边填绝对路径：Docker 容器里是
/var/www/html/，就填这个；WSL 里是/home/user/project，就填这个；别填宿主机路径 - 右边统一用
${folder}，前提是 Sublime 打开的是整个项目文件夹（有.sublime-project或根目录含index.php等），不是单个.php文件 - 示例（Linux 容器环境）：
"pathMappings": { "/var/www/html/": "${folder}/" } - Windows 用户注意反斜杠：左边要写成
C:\www\project\，右边仍用${folder}/ - 路径末尾都带斜杠，少一个都会导致映射失败
启动调试前必须完成三件事
Debugger 不会自动触发调试，它只监听。少一步，断点永远不生效。
- 在 PHP 文件中点击行号左侧空白处设断点，看到红点才算生效；灰色点 = 映射失败或文件未被加载
- 浏览器装
Xdebug Helper插件，并手动点击虫子图标启用（仅安装不启用 = 无效） - 访问 URL 时必须带
?XDEBUG_SESSION_START=1参数，例如http://localhost/index.php?XDEBUG_SESSION_START=1；只打开页面不带参数 = Xdebug 不发连接 - PHP 文件开头必须有
<?php，否则 Xdebug 直接跳过，Sublime 完全无提示 - 确保 Sublime 启动时能读到你的 shell PATH 和 php.ini —— 如果你是从桌面图标启动 Sublime，它很可能压根没加载你的开发环境变量
最常被忽略的一点：Xdebug 是否真正在往外发连接。用 telnet 127.0.0.1 9003 测试端口是否可通（注意：这是测试 PHP 进程能否连上 Sublime，不是测试 Sublime 能否连上 PHP）。不通，就不是 Sublime 配置问题，而是 Xdebug 没起来或被防火墙拦了。
