FrankenPHP容器里怎么开Xdebug远程调试-php教程-PHP中文网

frankenphp 官方镜像默认不包含 xdebug，需挂载 xdebug.ini（启用 zend_extension、xdebug.mode=debug、client_host=host.docker.internal 等），配置 phpstorm 路径映射并监听 9003 端口，通过日志验证连接。

frankenphp容器里怎么开xdebug远程调试

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 片段。推荐后者，更清晰可控。

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

准备一个 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 错误会导致断点不命中。

在 PHPStorm 中打开 Run > Start Listening for PHP Debug Connections
进入 Settings > PHP > Servers，新增服务器：
- Name：任意，如 frankenphp-local
- Host：填 localhost（不是容器名）
- Port：填你浏览器访问的端口（如 8000）
- Debugger：选择 Xdebug
最关键一步：点击 Use path mappings，添加映射：
- File/Directory：选项目根目录（如 /Users/you/project）
- Absolute path on server：填容器内路径，通常是 /app（FrankenPHP 默认工作目录）
验证：访问 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 显式声明