必须只设xdebug.mode=debug且xdebug.start_with_request=trigger；ThinkPHP单入口要求以public/index.php启动调试，Windows路径映射需将Remote path设为/、Local path设为项目根目录（如E:/www/project），而非public子目录。
能快速接入，但必须绕开ThinkPHP单入口和Xdebug路径映射这两个坑，否则断点永远不命中。
确认Xdebug 3的mode和启动方式是否正确
ThinkPHP对Xdebug的加载非常敏感，xdebug.mode=develop,debug或xdebug.mode=debug,develop都会导致调试器在框架初始化阶段就挂掉——不是报错，而是静默失效。必须只留debug：
-
xdebug.mode = debug（不能带develop） -
xdebug.start_with_request = trigger（不是yes，避免每次HTTP请求都拉起调试会话，干扰ThinkPHP路由解析） - 重启PHP服务后，执行
php -v，输出里必须含Xdebug v3.x.x和Mode: debug，不含develop
断点不触发？检查IDE监听和idekey是否匹配入口文件
ThinkPHP是单入口架构，public/index.php才是真实启动点。你在app/controller/里打的断点，IDE根本不会去监听——它只连index.php进程。
- PHPStorm必须开启
Run → Start Listening for PHP Debug Connections（小电话图标亮起） -
xdebug.idekey必须设为PHPSTORM（大小写敏感），且浏览器访问时带上?XDEBUG_SESSION_START=PHPSTORM - 别在控制器文件上右键「Debug」，要以
public/index.php为脚本手动启动调试会话 - 终端执行
lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows），确认端口被IDE进程占用
Windows下路径映射失败：别信“映射为/”这种万能解法
在Wamp/XAMPP等Windows环境里，public/index.php的真实路径是E:\www\project\public\index.php，但Xdebug发给IDE的路径可能是E:/www/E:\www\project\public\index.php——路径被重复拼接，IDE找不到本地文件。
立即学习“PHP免费学习笔记（深入）”；
- PHPStorm中打开
Preferences → PHP → Servers，添加服务器，Name填任意，Host填loc.project.com（对应hosts和虚拟主机配置） - 在
Debugger → Path Mapping里，Remote path填/，Local path填你项目根目录的绝对路径（如E:/www/project），不是public子目录 - 确保Apache虚拟主机
DocumentRoot指向project/public，且hosts里有127.0.0.1 loc.project.com
页面卡死或502？立刻调低xdebug.max_nesting_level
ThinkPHP的容器绑定、模板编译、中间件链层层嵌套，Xdebug默认xdebug.max_nesting_level=256极易溢出。尤其开启trace或profile时，直接阻塞响应。
- 临时调试阶段，把
xdebug.max_nesting_level设为500（设太高反而更易崩溃） - 禁用无关功能：
xdebug.collect_params=0、xdebug.collect_return=0，只保留xdebug.mode=debug - 生产环境严禁开启Xdebug——哪怕只是
xdebug.mode=off，也建议用php -d xdebug.mode=off index.php临时绕过
真正卡住人的从来不是装不上Xdebug，而是IDE连上了、断点打了、URL参数也加了，却始终停不下来——问题大概率出在入口文件没对上，或者Windows路径映射错了一层斜杠。
