FrankenPHP 官方镜像默认不包含 Xdebug，需挂载 xdebug.ini（启用 zend_extension、xdebug.mode=debug、client_host=host.docker.internal 等），配置 PHPStorm 路径映射并监听 9003 端口，通过日志验证连接。
Xdebug 在 FrankenPHP 容器里默认不启用，且不能直接复用传统 PHP-FPM 的配置方式；必须手动挂载配置、启用 xdebug.mode=debug，并确保容器网络能连通 IDE（如 PHPStorm）的调试客户端。
确认 FrankenPHP 镜像是否内置 Xdebug
FrankenPHP 官方镜像（docker.io/dunglas/frankenphp）从 v1.0 起默认**不包含 Xdebug** —— 它主打轻量、安全、现代 PHP 运行时，Xdebug 被视为开发期可选组件。你无法靠 php -m | grep xdebug 直接看到它。
- 运行
docker exec -it your-frankenphp-container php -m，若无xdebug输出，说明未加载 - 不要尝试在容器内用
pecl install xdebug：FrankenPHP 镜像没装php-dev和编译工具链，会失败 - 正确做法是：使用带 Xdebug 的定制镜像，或基于官方镜像多阶段构建
用自定义 Dockerfile 启用 Xdebug 3
FrankenPHP 不支持 php.ini 动态覆盖，必须通过 FRANKENPHP_INI 环境变量或挂载 INI 片段。推荐后者，更清晰可控。
- 准备一个
xdebug.ini文件（放在项目根目录）：
zend_extension=xdebug.so xdebug.mode=debug xdebug.client_host=host.docker.internal xdebug.client_port=9003 xdebug.start_with_request=yes xdebug.log=/tmp/xdebug.log
- 在
docker-compose.yml中挂载该文件，并确保容器能访问宿主机的 IDE：
services:
app:
image: dunglas/frankenphp
volumes:
- ./xdebug.ini:/etc/php/conf.d/99-xdebug.ini
- ./public:/app/public
environment:
- FRANKENPHP_INI=/etc/php/conf.d/99-xdebug.ini
# 关键：让 Linux/macOS 宿主机网络对容器可见
extra_hosts:
- "host.docker.internal:host-gateway"- Windows WSL2 用户注意：
host.docker.internal默认可用；纯 Windows Docker Desktop 也支持，无需额外配置 -
xdebug.client_port必须和 PHPStorm 的Settings > PHP > Debug > DBGp Proxy > Port一致（默认 9003，不是旧版的 9000）
PHPStorm 侧必须配对监听 + 路径映射
FrankenPHP 使用 SAPI 模式（非 FPM），IDE 无法自动识别请求来源路径，path mapping 错误会导致断点不命中。
立即学习“PHP免费学习笔记（深入）”；
- 在 PHPStorm 中打开
Run > Start Listening for PHP Debug Connections - 进入
Settings > PHP > Servers，新增服务器：- Name：任意，如
frankenphp-local - Host：填
localhost（不是容器名） - Port：填你浏览器访问的端口（如 8000）
- Debugger：选择
Xdebug
- Name：任意，如
- 最关键一步：点击
Use path mappings，添加映射：- File/Directory：选项目根目录（如
/Users/you/project） - Absolute path on server：填容器内路径，通常是
/app（FrankenPHP 默认工作目录）
- File/Directory：选项目根目录（如
- 验证：访问
http://localhost:8000/?XDEBUG_SESSION_START=PHPSTORM，看 PHPStorm 是否弹出 “Incoming Connection” 提示
常见失败点：网络不通 + mode 设置遗漏
90% 的“连不上”问题出在这两个地方，不是配置写错，而是根本没走通链路。
-
xdebug.mode=debug是 Xdebug 3 的开关总闸，漏写或拼错成develop/develop,debug都无效 - 容器无法解析
host.docker.internal？检查 Docker 版本（≥20.10），或临时改用宿主机真实 IP（如192.168.1.5），但要确保防火墙放行 9003 端口 -
xdebug.log日志是唯一真相：进容器执行tail -f /tmp/xdebug.log，发起请求后看是否有Connection to 'host.docker.internal:9003' failed或sent create packet - FrankenPHP 的
FRANKENPHP_INI只影响 PHP 解释器启动参数，不接管 Xdebug 加载逻辑；扩展仍需zend_extension显式声明
FrankenPHP 的 Xdebug 调试本质仍是标准 DBGP 协议通信，但它把“PHP 进程托管权”交给了自己的 runtime，所以路径映射和 client_host 的准确性比传统 FPM 更敏感——别跳过日志验证这步。
