FrankenPHP 配置全指南：从基础到高级应用

FrankenPHP 配置全指南：从基础到高级应用

作为一款创新的PHP运行时环境，FrankenPHP提供了灵活的配置选项来满足不同场景下的需求。本文将全面解析FrankenPHP的配置体系，帮助开发者掌握其核心配置方法。

一、配置体系概述

FrankenPHP的配置系统建立在Caddy服务器的基础上，同时集成了PHP特有的配置方式。主要包含三个层面的配置：

1. Caddyfile：用于配置Web服务器行为
2. php.ini：标准的PHP运行时配置
3. 环境变量：动态调整配置参数

二、PHP运行时配置

2.1 配置文件位置

根据部署方式不同，PHP配置文件的存放位置有所差异：

Docker部署

• 主配置文件：/usr/local/etc/php/php.ini（默认不存在）
• 附加配置：/usr/local/etc/php/conf.d/*.ini
• 扩展目录：/usr/local/lib/php/extensions/no-debug-zts-<日期>/

系统包安装(.rpm/.deb)

• 主配置文件：/etc/frankenphp/php.ini（默认提供生产环境配置）
• 附加配置：/etc/frankenphp/php.d/*.ini
• 扩展目录：/usr/lib/frankenphp/modules/

静态二进制部署

• 主配置文件：执行目录或/etc/frankenphp/php.ini
• 附加配置：/etc/frankenphp/php.d/*.ini
• 注意：静态二进制不支持动态加载扩展

2.2 配置建议

对于生产环境，建议使用php.ini-production模板；开发环境则使用php.ini-development。在Docker中可以通过以下方式应用模板：

FROM dunglas/frankenphp

# 生产环境配置
RUN cp $PHP_INI_DIR/php.ini-production $PHP_INI_DIR/php.ini

# 或开发环境配置
RUN cp $PHP_INI_DIR/php.ini-development $PHP_INI_DIR/php.ini

三、Caddyfile配置详解

3.1 基础配置示例

最简单的Caddyfile配置如下：

localhost {
    # 启用压缩（可选）
    encode zstd br gzip
    # 执行当前目录下的PHP文件并服务静态资源
    php_server
}

3.2 全局配置选项

通过frankenphp全局块可以进行高级配置：

{
    frankenphp {
        num_threads 8 # 设置PHP线程数，默认是CPU核心数的2倍
        
        worker {
            file /path/to/worker.php # worker脚本路径
            num 4 # worker线程数
            env KEY VALUE # 设置环境变量
            watch # 监听文件变化
        }
    }
}

3.3 多应用配置

单个FrankenPHP实例可以服务多个应用：

app1.example.com {
    php_server {
        root /path/to/app1/public
        worker index.php 4
    }
}

app2.example.com {
    php_server {
        root /path/to/app2/public
        worker index.php 2
    }
}

四、开发环境特殊配置

4.1 文件监听机制

开发时可通过watch指令实现代码热更新：

{
    frankenphp {
        worker {
            file /path/to/worker.php
            watch /path/to/app/**/*.{php,twig} # 监听PHP和Twig文件变化
        }
    }
}

支持的通配符模式：

• **：递归匹配所有子目录
• *.php：匹配当前目录PHP文件
• **/*.{php,twig}：匹配所有PHP和Twig文件

4.2 调试模式

在Docker中启用调试模式：

docker run -v $PWD:/app/public \
    -e CADDY_GLOBAL_OPTIONS=debug \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

五、高级特性配置

5.1 全双工模式(HTTP/1)

启用HTTP/1.x全双工通信：

{
    servers {
        enable_full_duplex
    }
}

注意：旧版客户端可能不支持此特性。

5.2 环境变量配置

常用环境变量：

• SERVER_NAME：修改监听地址
• CADDY_GLOBAL_OPTIONS：添加全局选项
• FRANKENPHP_CONFIG：添加FrankenPHP特定配置
• PHP_INI_SCAN_DIR：指定附加PHP配置目录

六、最佳实践建议

1. 生产环境务必使用php.ini-production配置
2. 合理设置worker数量（通常为CPU核心数的1-2倍）
3. 开发环境启用文件监听，但避免监听日志等频繁变化的文件
4. 多应用部署时为每个应用分配独立的worker
5. 全双工模式仅在实际需要时启用

通过本文的详细讲解，开发者应该能够根据实际需求灵活配置FrankenPHP，充分发挥其高性能特性。无论是简单的单应用部署还是复杂的多应用场景，FrankenPHP都提供了相应的配置方案来满足需求。