Sublime Text 本身不带调试功能，需通过Debugger插件作为DAP客户端连接外部调试适配器；配置关键在于正确放置.sublime-debugger文件、匹配debugpy版本（推荐1.6.7）、指定Python绝对路径、对齐PHP的pathMappings及确保xdebug.mode=debug。
Sublime Text 本身不带 Debug 模式，所谓“开启 Debug 模式”其实是配置调试器插件并让它与外部调试适配器（如 debugpy、xdebug、vscode-js-debug）通信——不是 Sublime 自己在跑调试逻辑，它只是个 DAP 客户端。
Debugger 插件不工作？先确认它是否真在监听
装完 Debugger 插件后，状态栏右下角没出现 Debugger: Python 或 Debugger: PHP，说明配置根本没加载。常见原因：
-
.sublime-debugger文件名写错（必须带点，不能叫launch.json或debug.json） - 文件放在了错误位置：必须在项目根目录，或用户 Packages 目录下（
Preferences → Browse Packages可定位） - JSON 格式非法：Windows 路径里单反斜杠
会静默破坏解析，得用/或\ - 顶层不是
"configurations": []数组，或者某个配置缺了"type"、"request"、"name"
Python 断点不命中？大概率是 debugpy 版本或路径不对
Debugger 依赖 debugpy 后端，但不是所有版本都兼容。2026 年主流稳定组合是 debugpy==1.6.7（pip install debugpy==1.6.7）。
- 别用
debugpy>=1.8：默认启用新协议，旧版Debugger插件握手失败，日志里会报Protocol mismatch -
"python"字段必须填绝对路径，比如/opt/homebrew/bin/python3，不能只写python—— Sublime 启动时通常不继承 shell 的PATH - virtualenv 环境下，路径必须是激活后的解释器全路径，否则断点加载失败，变量显示
undefined
PHP 断点一直灰？pathMappings 和 xdebug.mode 是关键
断点变灰色 = Debugger 认为“这个文件不在运行路径里”，90% 是 pathMappings 左右两边没对齐。
- 左边必须是 PHP 实际执行时看到的绝对路径，比如 Docker 容器里是
/var/www/html/，就填这个，不是宿主机路径 - 右边用
${folder}表示当前项目根目录，确保 Sublime 打开的是整个项目文件夹，不是单个 .php 文件 - Xdebug 3.x 必须设
xdebug.mode=debug，旧配置如xdebug.remote_enable=1会被忽略 - 端口默认是
9003，改过就得同步改"port": 9003，且确保xdebug.client_port=9003一致
按下 F5 没反应？你可能卡在“等连接”阶段
Debugger 不主动发起调试，它只监听。F5 启动后，它就在等 debugpy 或 xdebug 主动连过来。所以：
- Python：要么提前在终端运行
python -m debugpy --listen 5678 --wait-for-client，再按 F5；要么在配置里加"preLaunchTask"触发 - PHP：必须用浏览器访问带参数的 URL，比如
http://localhost/index.php?XDEBUG_SESSION_START=1，或装 Xdebug Helper 插件点虫子图标 - 检查端口是否被占：
lsof -i :5678（macOS/Linux）或netstat -ano | findstr :9003（Windows） - Windows 防火墙常默默拦截 9003，临时关掉试试
最易被忽略的点：Sublime 启动方式决定它能否读到你的环境变量和 php.ini。从 Dock 或开始菜单点开的 Sublime，和从终端执行 subl . 启动的，加载的 PATH 和配置可能完全不同——断点失效却查不出原因，往往就卡在这里。
