PHP断点调试需满足“四对齐”：进程连IDE端口、触发信号、协议端口、路径映射、IDE Key全部匹配；Xdebug 3仅认xdebug.mode=debug、xdebug.start_with_request=trigger、xdebug.client_host/port三行配置。
PHP网站调试不是配完扩展就自动断点，核心在于“四对齐”：PHP进程能主动连上IDE监听端口，且触发信号、协议端口、路径映射、IDE Key全部匹配——缺一不可。
断点调试必须满足的硬性条件
Xdebug 3 不再响应旧式 remote_ 配置，只认三行关键设置：
- xdebug.mode=debug：必须是 debug，不能写 develop 或 profile
- xdebug.start_with_request=trigger：仅在收到明确启动信号时连接，更安全（避免干扰队列或健康检查）
- xdebug.client_host 和 xdebug.client_port：本地开发填 127.0.0.1:9003；Docker 内 PHP 容器必须填 host.docker.internal（不是 localhost），端口需与 IDE 监听端口完全一致
浏览器访问不触发？不是 Xdebug 没装，而是没带启动参数：?XDEBUG_SESSION_START=PHPSTORM（PhpStorm 默认 IDE Key）或 ?XDEBUG_SESSION_START=VSCODE（VS Code）。推荐安装官方 Xdebug Helper 插件，一键注入 Cookie，比手拼 URL 更可靠。
断点不命中？先查这五件事
断点变灰、控制台报 Connection refused、日志里没连接记录——大概率卡在这几个环节：
立即学习“PHP免费学习笔记（深入）”；
- 执行
php --ri xdebug，确认输出中 xdebug.mode 包含 debug，且 xdebug.client_host/port 与 IDE 设置完全一致 - PHPStorm 必须勾选 Settings > PHP > Debug > Xdebug > Can accept external connections，否则直接丢弃连接请求
- Docker 或远程环境，Settings > PHP > Servers 中要添加对应 host，并启用 Use path mappings，把容器内绝对路径（如 /var/www/html）映射到本地项目路径
- CLI 脚本调试不用 URL 参数，改用命令行环境变量：
XDEBUG_CONFIG="idekey=PHPSTORM" php script.php - 加一行
xdebug.log=/tmp/xdebug.log，出问题第一眼就看它——日志里会明确写出连接失败原因（如 Connection refused、path not found）
性能分析：从慢接口定位瓶颈
发现某个 API 响应慢，别急着改代码。用 Xdebug 的 profile 模式生成调用图，精准定位耗时大户：
- 临时开启：在 php.ini 加两行
xdebug.mode=profile和xdebug.start_with_request=trigger，访问时带上?XDEBUG_PROFILE=1 - 指定输出目录：
xdebug.output_dir=/tmp（确保 PHP 进程有写权限） - 生成文件默认为
cachegrind.out.*，用 PhpStorm 或 KCacheGrind 打开，直观看到函数调用层级和耗时占比 - 配合 Tracy 使用效果更佳：Tracy 调试栏先标出慢请求，再用 Xdebug profile 深挖该请求内部哪一行、哪个方法拖慢了整体
高级技巧提升调试效率
普通断点只是起点，真正省时间的是这些进阶用法：
-
条件断点：在循环或高频调用处右键断点 → Edit Breakpoint → 填入表达式（如
$user_id === 42），只在目标数据出现时暂停 -
异常断点：PhpStorm 中打开 Run > View Breakpoints > + > PHP Exception Breakpoints，勾选
E_WARNING或自定义异常类，抛异常瞬间就停住 -
监视点（Watch Expression）：在 Debug 工具窗口点 + 号，输入变量名或表达式（如
count($items)），值一变立即中断，适合追踪被意外修改的状态 - 跳过框架代码：在 Settings > PHP > Debug > Stepping 中启用 Ignore external libraries，单步调试时自动跳过 vendor 下的代码
