远程容器调试断点不触发，根本原因是PHP进程无法连接PhpStorm：Xdebug 3需PHP主动连IDE，须确认扩展启用、配置仅含xdebug.mode=debug等三行、client_host设为host.docker.internal（Linux用172.17.0.1）、PhpStorm选Docker Compose解释器并精确配置路径映射与端口9003，且通过XDEBUG_SESSION_START=PHPSTORM触发。
远程容器调试断点不触发，大概率不是Xdebug没装，而是PHP进程根本连不上PhpStorm——Xdebug 3要求PHP主动连IDE，不是反过来。配错方向，断点必然静默失效。
确认Xdebug 3在容器内已启用debug模式
别只看php -v里带Xdebug就放心。进容器执行：
-
php -m | grep xdebug确认扩展已加载 -
php --ini查出实际生效的配置文件（常是/usr/local/etc/php/conf.d/xdebug.ini） - 该文件中必须只有三行核心配置，且不能混用
xdebug.remote_*旧参数（它们会让Xdebug加载失败或静默降级）：
xdebug.mode=debug xdebug.start_with_request=trigger xdebug.client_host=host.docker.internal
注意：host.docker.internal适用于macOS/Windows；Linux Docker默认网桥需改用172.17.0.1。若填127.0.0.1，PHP会连自己，不是宿主机。
PhpStorm必须通过docker-compose.yml配置Remote Interpreter
直接docker run启的容器，PhpStorm无法识别服务名和路径映射，断点必灰。关键点：
立即学习“PHP免费学习笔记（深入）”；
- 解释器类型选 Docker Compose，不是“Docker”或“SSH”
- Service name 填
docker-compose.yml里services:下的服务名（如php），不是容器名（如myapp_php_1） - Interpreter path 固定填
/usr/bin/php（Debian/Alpine通用），别写/bin/sh -c "php" - 路径映射（Path Mapping）必须手动对齐，且大小写100%精确匹配
例如本地项目根路径是/Users/me/project，容器挂载路径是/var/www/html，那么File/Directory必须填前者全路径，Absolute path on server必须填后者，字母大小写一个都不能错。
确保PhpStorm监听端口与Xdebug client_port一致
PhpStorm 2022.3+ 默认监听9003，不是Xdebug 2时代的9000。检查两处：
- Settings > PHP > Debug > Xdebug > Debug port 必须是
9003 - 容器内
xdebug.client_port必须设为9003（默认值，但显式写出更稳妥） - 右上角电话图标（Start Listening for PHP Debug Connections）必须点亮，状态栏显示“Debug listening…”
如果xdebug.log里出现Connection to 'host.docker.internal:9003' failed，先用lsof -i :9003（macOS/Linux）或netstat -ano | findstr :9003（Windows）确认端口是否真被PhpStorm占用——被其他进程（如旧版IDE、VS Code）占着，就会连不上。
触发调试必须带有效IDE key和URL参数
即使配置全对，没触发信号，Xdebug也不会启动调试会话。两种可靠方式：
- 浏览器访问时URL带上
XDEBUG_SESSION_START=PHPSTORM（注意大小写） - 装Xdebug Helper插件，IDE Key设为
PHPSTORM，并激活（图标变绿色）
别依赖xdebug.start_with_request=yes——它会让每个请求都进调试，性能差，且容易被Web服务器（如Nginx）的缓存或重定向机制绕过。用trigger更可控，也更符合生产环境调试习惯。
最隐蔽的失败点永远是路径映射大小写不一致，或client_host填了localhost而不是host.docker.internal。这两处一错，Xdebug日志里连连接尝试都不会有，只会安静地跳过断点。
