FrankenPHP 在 Laravel 项目中实现 Worker 模式的实践指南

背景介绍

FrankenPHP 是一个高性能的 PHP 运行时环境，它通过集成 Caddy 服务器提供了现代化的 PHP 运行方式。在 Laravel 项目中，开发者常常需要实现 Worker 模式来处理队列任务或长时运行进程，而 FrankenPHP 提供了这样的能力。

常见配置误区

许多开发者在初次尝试 FrankenPHP 的 Worker 模式时会遇到一些典型问题：

1. 端口冲突问题：当同时运行 Nginx 和 FrankenPHP 时，443 端口可能被占用。解决方案是在 FrankenPHP 配置中明确关闭自动 HTTPS 功能。

2. Worker 配置错误：直接使用 --worker 参数启动 FrankenPHP 会导致失败，因为正确的 Worker 模式需要在 Caddyfile 中配置。

3. Worker 进程异常退出：如果 Worker 脚本配置不当，会导致进程不断重启。

正确配置方法

基础配置

在 Laravel 项目的 Caddyfile 中，应包含以下基本配置：

{
    frankenphp
    order php_server before file_server
    auto_https off
}

Worker 模式配置

有两种可行的 Worker 模式配置方案：

方案一：直接使用 Laravel 入口文件

frankenphp {
    worker public/index.php 2
}

方案二：结合 Laravel Octane

1. 安装 Laravel Octane 包
2. 运行 php artisan octane:install 命令
3. 配置 FrankenPHP 使用 Octane 提供的 Worker 文件：

frankenphp {
    worker {
        file /app/public/frankenphp-worker.php
    }
}

性能优化建议

1. Worker 数量：根据服务器 CPU 核心数合理设置 Worker 数量，通常建议设置为 CPU 核心数的 1-2 倍。

2. 请求限制：可以设置 max_request 参数来定期重启 Worker，防止内存泄漏。

3. 编码压缩：启用 encode zstd gzip 可以显著减少网络传输量。

常见问题解决方案

1. Worker 不断重启：检查 Laravel 应用是否有未捕获的异常，确保 Worker 脚本能够稳定运行。

2. 端口冲突：确保 FrankenPHP 和 Nginx 使用不同的端口，或者在 Nginx 中配置反向代理。

3. HTTPS 问题：如果已有 Nginx 处理 HTTPS，应在 FrankenPHP 中关闭自动 HTTPS 功能。

最佳实践

对于 Laravel 项目，推荐使用 Laravel Octane 与 FrankenPHP 结合的方案。Octane 专为高性能 Laravel 应用设计，提供了更好的进程管理和请求处理机制。配置完成后，可以通过简单的 ./frankenphp run 命令启动服务，无需额外参数。

通过合理配置，FrankenPHP 可以为 Laravel 应用提供接近传统 PHP-FPM 两倍的性能提升，同时保持开发的便捷性。