断点变灰不触发，说明xdebug未成功连接ide，需依次检查：一、php --ri xdebug确认xdebug.mode=debug；二、phpinfo()验证xdebug加载及client_port与ide一致；三、启用xdebug.log查连接日志；四、严格校准pathmappings路径映射；五、通过url参数或插件触发调试请求。
断点变灰不触发？先确认 Xdebug 是否真在发连接
断点显示为灰色，不是 Sublime 的锅，而是 Debugger 根本没收到 Xdebug 的连接请求。Xdebug 是主动方，Sublime 只是监听端口的被动接收者。
- 执行
php --ri xdebug，检查输出里是否有xdebug.mode => debug，没有就说明配置未生效 - 访问
phpinfo()页面，搜索Xdebug，确认模块已加载且client_port值与 Sublime 配置一致（Xdebug 3.x 默认是9003，不是9000） - 加一行
xdebug.log="/tmp/xdebug.log"（Linux/macOS）或xdebug.log="C:\xdebug.log"（Windows），然后触发一次页面请求，打开日志看有没有Connecting to或connection failed
pathMappings 映射错一个斜杠，断点就失效
这是 70% 断点失败的根源。左边是 PHP 运行时看到的绝对路径，右边是 Sublime 当前打开的项目根目录，二者必须严格一一对应，包括末尾斜杠和正斜杠方向。
- Linux/Docker 环境示例：
"/var/www/html/": "${folder}/"—— 左边反斜杠转义，右边用${folder}表示当前项目根 - Windows 用户注意：
C:wwwproject在 JSON 中必须写成"C:/www/project/"，反斜杠会导致解析失败 - 路径末尾的斜杠不能省略，
"/var/www/html"和"/var/www/html/"对 Debugger 来说是两个不同路径 - 如果用 WSL，左边填
/home/user/project/，不是 Windows 下的D:projects...
浏览器没反应？你可能根本没发调试请求
Debugger 不监听所有 HTTP 请求，只响应带 XDEBUG_SESSION_START 参数或 cookie 的请求。单纯刷新页面不会触发断点。
- 手动在 URL 后加
?XDEBUG_SESSION_START=1，例如http://localhost/index.php?XDEBUG_SESSION_START=1 - 装浏览器插件（如 Xdebug Helper），点击甲壳虫图标启用调试模式，它会自动注入 cookie
- 别依赖 “Start Debugging (Launch Browser)” 按钮——它只负责打开浏览器，不自动加参数；必须确保页面加载时已携带调试标识
- 如果用 curl 测试，加头：
curl -H "Cookie: XDEBUG_SESSION=1" http://localhost/index.php
该用 Debugger 插件，而不是 SublimeXdebug
截至 2026 年，Debugger 是唯一稳定支持 Xdebug 3.x + PHP 8.2+ + DAP 协议的插件。SublimeXdebug 已停止维护，对 super_globals、多路径映射、异步请求支持极差，变量常为空或断点跳过。
- 通过 Package Control 安装
Debugger，不要搜SublimeXdebug或Xdebug Client - 安装后走
Tools → Debugger → Open Launch Configurations，选 PHP 模板生成配置，避免手写 JSON 出错 - 状态栏右下角出现
Debugger: PHP才算配置加载成功；没出现说明 JSON 语法错误或pathMappings格式不对 - 配置中必须有
"type": "php"、"port": 9003、"pathMappings"三项，缺一不可
connection refused，可能只是端口没对齐；断点灰色，大概率是 pathMappings 左右两边路径差了一个字符。这些细节不逐行核对，再熟练的操作也会停在第一步。
