sublime text 本身不运行 php，也不内置调试器，所谓“配置 xdebug 调试环境”，本质是让 sublime 成为 xdebug 的 xml 协议接收端——只要 xdebug.mode=debug 生效、xdebug.client_port 端口通、pathmappings 左右路径严丝合缝，断点就能命中；其余全是干扰项。
Sublime Text 本身不运行 PHP，也不内置调试器，所谓“配置 Xdebug 调试环境”，本质是让 Sublime 成为 Xdebug 的 XML 协议接收端——只要 xdebug.mode=debug 生效、xdebug.client_port 端口通、pathMappings 左右路径严丝合缝，断点就能命中；其余全是干扰项。
确认 Xdebug 3.x 已加载且配置生效
90% 的“断点不触发”问题，根源在此。Sublime 不会报错，只会静默等待一个永远不会来的连接。
- 访问
phpinfo()页面，搜索Xdebug，必须看到模块信息，且xdebug.mode值为debug（不是remote_enable=1） - 终端执行
php -m | grep xdebug，有输出才说明 CLI 层也加载了——很多用户只配了 Web 的php.ini，忘了改 CLI 的 - 在
php.ini中确认含以下最小配置（Xdebug 3.x 必须）：xdebug.mode=debug<br>xdebug.start_with_request=trigger<br>xdebug.client_host=127.0.0.1<br>xdebug.client_port=9003
- 加一行
xdebug.log="/tmp/xdebug.log（Linux/macOS）或xdebug.log="C:\xdebug.log"（Windows），出问题直接看日志里有没有connection failed或connecting to
用 Debugger 插件而非 SublimeXdebug
截至 2026 年，SublimeXdebug 已停止维护，不支持 PHP 8.2+、Docker 路径映射、$_SESSION 变量展开，且对 Xdebug 3.x 的 DAP 协议兼容极差。
- 通过 Package Control 安装
Debugger（搜关键词 “Debugger”，不是 “Xdebug”） - 安装后走
Tools → Debugger → Open Launch Configurations，选 PHP 模板自动生成配置，不要手写 JSON - 生成的配置中，
"type": "php"不可改为"xdebug"或其他值；"port": 9003必须与php.ini中的xdebug.client_port一致 - 保存后状态栏右下角出现
Debugger: PHP才算配置加载成功；没出现，大概率是配置文件没保存在项目级.sublime-project中，或 JSON 语法错误
pathMappings 必须左右绝对路径严格对齐
断点变灰色、变量显示 undefined、跳转到错误文件——几乎全是 pathMappings 填错了。它不是“本地 → 本地”，而是“PHP 运行时看到的路径 → 你 Sublime 里打开的路径”。
- 左边填 PHP 实际执行时的绝对路径：Docker 容器里是
/var/www/html/，就填这个；WSL 是/home/user/project/，就填这个；别填宿主机路径 - 右边统一用
${folder}/，前提是 Sublime 打开的是整个项目文件夹（有.sublime-project或根目录含index.php），不是单个.php文件 - Windows 用户注意反斜杠转义：左边写成
C:\www\project\，右边仍用${folder}/；两边末尾都必须带斜杠，少一个都会映射失败 - 示例（Linux 容器环境）：
"pathMappings": { "/var/www/html/": "${folder}/" }
启动调试前必须满足三个硬性条件
Debugger 不主动发起调试，它只监听。F5 启动后，它就在等 Xdebug 主动连进来——缺一不可。
- PHP 脚本开头必须有
<?php，否则 Xdebug 直接跳过整个文件，Sublime 静默无反应 - 浏览器必须安装 Xdebug Helper（Chrome/Firefox），IDE key 设为
sublime.xdebug，并手动点击虫子图标启用（仅安装不启用 = 无效） - 访问 URL 必须带
?XDEBUG_SESSION_START=sublime.xdebug参数，或依赖插件自动注入；只打开index.php不加参数 = 不触发 - macOS/Linux 用户注意：从 Dock 或 Spotlight 启动 Sublime，它不继承终端里的
PATH和 shell 配置；必须在终端执行subl .启动项目，否则可能读不到正确的php.ini
最易被忽略的是：Xdebug 是 PHP 进程主动往外连 Sublime，不是反过来。所以所有验证都要围绕“PHP 能不能连出去”展开，而不是“Sublime 能不能连进去”。端口通不通、路径对不对、配置是不是真生效，三者缺一，断点就永远是灰色的。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
