PhpStorm 调试 Docker 中 PHP 需 Xdebug 3 主动连宿主机 9003 端口，配置须含 xdebug.mode=debug、start_with_request=trigger、client_host 正确指向 host.docker.internal 或 172.17.0.1；必须通过 docker-compose.yml 配置 Remote Interpreter，路径映射须大小写精确匹配，且确保 PhpStorm 监听开启、URL 带 XDEBUG_SESSION_START、xdebug.log 有连接日志、9003 端口未被占用。
PhpStorm 调试 Docker 容器里的 PHP 代码，关键不在“能不能连上”，而在于“谁主动连谁”——Xdebug 3 是 PHP 进程主动连接 PhpStorm 监听的 9003 端口，不是反过来。配错方向（比如让 PhpStorm 去连容器 IP），断点必然静默失效。
确认 Xdebug 3 已在容器内正确加载并启用 debug 模式
别信 php -v 里带 Xdebug 就万事大吉。必须进容器执行 php -m | grep xdebug 和 php --ini，再检查实际生效的 php.ini 或独立配置文件（如 /usr/local/etc/php/conf.d/xdebug.ini）是否只含这三行核心配置：
xdebug.mode=debug-
xdebug.start_with_request=trigger（或yes，但trigger更安全） -
xdebug.client_host=host.docker.internal（Windows/macOS）或172.17.0.1（Linux Docker 默认网桥）
删掉所有 xdebug.remote_* 开头的旧参数（xdebug.remote_host 等），它们在 Xdebug 3 中已废弃，混用会导致 xdebug_info() 显示已加载但断点不触发。
PhpStorm 必须通过 Docker Compose 配置 Remote Interpreter
直接用 docker run 启的容器，PhpStorm 根本发现不了——它只认 docker-compose.yml 里 services: 下定义的服务。常见错误现象：Cannot resolve path mapping 或断点灰色不可用，八成是这一步没走对。
- 路径映射的本地目录必须和 PhpStorm 当前打开的项目根路径完全一致
- 容器内路径填绝对路径，例如
/var/www/html，不是相对路径或软链 - 解释器路径固定填
/usr/bin/php（Debian/Alpine 都适用），别写/bin/sh -c "php" - 选服务名（如
php），不是容器名（如myapp_php_1）
路径映射（Path Mapping）必须手动对齐，且区分大小写
这是断点不生效最隐蔽的坑：PhpStorm 认为“文件在容器里是 /var/www/html/index.php”，而你本地打开的是 E:\project\index.php，但映射却写成 E:\Project\（P 大写）——大小写不一致，路径就对不上。
- File/Directory 填 PhpStorm 项目根目录的**完整、准确、大小写匹配**的路径
- Absolute path on server 填容器内挂载后的**绝对路径**，和
docker-compose.yml的volumes:字段保持一致 - 如果用了 WSL2，宿主机路径可能是
/mnt/e/project/，别直接套 Windows 的E:\project\
调试启动前必须同时满足四个条件
少一个，请求发出去了，断点也下好了，但就是不动。最容易忽略的是第四条：
- PhpStorm 的
Start listening for PHP Debug Connections已开启（工具栏小电话图标变绿） - 浏览器访问 URL 带
?XDEBUG_SESSION_START=PHPSTORM，或装 Xdebug Helper 插件并点击激活 - 容器内
xdebug.log有连接尝试日志（可临时加xdebug.log=/tmp/xdebug.log查看） - 宿主机 9003 端口未被占用：
netstat -ano | findstr :9003（Windows）或lsof -i :9003（macOS/Linux）
路径映射和 client_host 设置，是两个最常因环境差异（Win/macOS/Linux + Docker Desktop/WSL2）而填错的地方，建议每次换机器都重新验证一次输出结果，而不是复用旧配置。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
