FrankenPHP 中 Xdebug 调试问题的分析与解决方案

在开发环境中，当使用 FrankenPHP 结合 Laravel Octane 和 Xdebug 进行调试时，开发者可能会遇到一个特殊现象：调试断点仅在通过 index.php 访问路由时触发，而直接访问路由时却无法正常工作。本文将深入分析这一问题的成因，并提供有效的解决方案。

问题现象分析

当开发者配置好 FrankenPHP 容器环境后，发现以下调试行为差异：

1. 访问类似 https://localhost/index.php/{route} 的 URL 时，Xdebug 断点可以正常触发
2. 直接访问 https://localhost/{route} 时，虽然页面能正常显示，但断点不会被触发

这种差异表明系统存在请求处理路径的分歧，核心问题在于请求如何被路由到 PHP 解释器。

根本原因

问题的根源在于 FrankenPHP 的两种不同运行模式：

1. CGI 模式：当请求显式包含 index.php 时，请求会以传统的 CGI 方式处理，每个请求都会新建一个 PHP 进程，Xdebug 可以正常附加调试会话。

2. Worker 模式：当使用 Laravel Octane 时，应用以长运行的工作进程方式处理请求。这种模式下，Xdebug 会话需要特殊处理才能保持连接。

解决方案

方案一：配置正确的重写规则

确保 Caddyfile 中包含正确的重写规则，将所有请求路由到 index.php：

rewrite * /index.php/{path}?{query}

这种配置可以强制所有请求通过 CGI 模式处理，确保 Xdebug 正常工作。

方案二：Worker 模式的 Xdebug 配置

如果必须使用 Worker 模式，需要对 Xdebug 进行特殊配置：

1. 在 php.ini 中添加：

xdebug.start_with_request=yes
xdebug.mode=debug

2. 在应用启动脚本中添加重连逻辑：

if (extension_loaded('xdebug')) {
    xdebug_connect_to_client();
}

方案三：Docker 环境优化

调整 Docker 配置以确保环境变量正确传递：

environment:
  XDEBUG_MODE: debug
  XDEBUG_CONFIG: client_host=host.docker.internal

最佳实践建议

1. 开发环境建议使用 CGI 模式，便于调试
2. 生产环境使用 Worker 模式以获得更好性能
3. 为不同环境创建独立的 Dockerfile 和配置
4. 考虑使用 PhpStorm 的路径映射功能确保调试器能找到正确源文件

总结

FrankenPHP 结合 Laravel Octane 提供了高性能的 PHP 运行环境，但在调试配置上需要特别注意运行模式的差异。通过理解 CGI 和 Worker 模式的区别，并正确配置 Xdebug，开发者可以获得流畅的调试体验。建议开发阶段使用方案一的 CGI 模式，部署前再切换至优化后的 Worker 模式配置。