因为Docker容器内127.0.0.1指向容器自身而非宿主机，Xdebug需连接宿主机上的PhpStorm，故必须用host.docker.internal（macOS/Windows）或宿主机局域网IP（Linux）。
为什么 xdebug.client_host 不能填 127.0.0.1？
在 Docker 容器里，127.0.0.1 指的是容器自己，不是宿主机。Xdebug 必须连到 PhpStorm 所在的宿主机，否则连接直接失败，调试会话根本发不出去。
正确值取决于你的系统：
- macOS：用
host.docker.internal（Docker Desktop 自动解析） - Windows（WSL2 或 Docker Desktop）：也优先用
host.docker.internal - Linux（原生 Docker）：没有内置别名，需手动查宿主机 IP，比如
ip route | awk 'NR==1 {print $3}'，或改用network_mode: host避开网络隔离
如果填错，php -i | grep xdebug.client_host 会显示你写的值，但日志里会出现 Connection refused 或超时，/var/log/xdebug.log 是第一排查位置。
xdebug.mode=debug 和 xdebug.start_with_request 怎么配才不漏断点？
Xdebug 3 默认不自动启动调试会话，只靠 URL 参数（如 ?XDEBUG_SESSION_START=PHPSTORM）太容易遗漏 —— 尤其是 API 请求、CLI 脚本、异步任务、Cron 等场景。
立即学习“PHP免费学习笔记（深入）”；
推荐组合：
-
xdebug.mode=debug（必需） -
xdebug.start_with_request=yes（强制所有请求都触发调试） -
xdebug.client_port=9003（与 PhpStorm 监听端口一致） -
xdebug.idekey=PHPSTORM（大小写敏感，必须和 PhpStorm 里配置完全一致）
不加 start_with_request 时，浏览器插件或书签工具（如 Xdebug Helper）必须全程开启，且仅对带 Cookie 或参数的 HTTP 请求有效；CLI 调试则完全失效。
PhpStorm 的 Path Mapping 为什么总映射失败？
这是远程调试最常卡住的环节：断点打了，连接也通了，但 PhpStorm 显示 “No path mapping for …”，断点灰色不可用。
关键点只有两个：
- “Absolute path on the server” 必须填容器内 PHP 实际运行代码的完整路径，例如
/var/www/html，不是挂载宿主机的路径（如/Users/xxx/project） - “Project files” 是你本地 PhpStorm 打开的项目根目录，必须和容器中路径一一对应 —— 不能多一级，也不能少一级，斜杠结尾与否要统一
验证方式：在容器里执行 pwd 进入代码目录，再 ls -la 确认当前路径；在 PhpStorm 中右键项目根目录 → “Copy Path”，粘贴比对。常见错误是把 /app 写成 /app/（末尾斜杠差异）、或把容器路径错写成 Docker Compose 里的 volume 源路径。
要不要上 DBGp Proxy？什么情况必须用？
单人本地开发 + Docker Desktop，不用 Proxy —— 直连更简单、延迟更低、配置项更少。
必须上 Proxy 的典型场景：
- 多人共用同一套测试环境（如 QA 服务器上的 Docker），否则 Xdebug 不知道该连谁的 PhpStorm
- 你的电脑在企业内网/NAT 后，远程服务器无法直连你本机（
client_host根本设不了） - Docker 容器跑在云服务器上，而你本地是动态公网 IP 或无公网 IP
Proxy 本质是中间转发器：xdebug.client_host 改为 Proxy 地址（如 proxy.example.com），xdebug.client_port 改为 Proxy 监听 Xdebug 的端口（如 9003）；PhpStorm 则通过 DBGp Proxy → IDE key → Host/Port 注册自己。一旦引入 Proxy，所有端口、host、idekey 必须三方严格对齐，错一个就静默失败。
