FrankenPHP项目配置完全指南：从基础到高级

FrankenPHP项目配置完全指南：从基础到高级

frankenphp The modern PHP app server 项目地址: https://gitcode.com/gh_mirrors/fr/frankenphp

前言

FrankenPHP作为一款创新的PHP运行时环境，其配置方式融合了Caddy服务器的灵活性和PHP本身的特性。本文将全面解析FrankenPHP的配置体系，帮助开发者掌握从基础到高级的配置技巧。

核心配置文件概述

FrankenPHP的配置主要分为两大体系：

1. Caddyfile配置：控制Web服务器行为和FrankenPHP特有功能
2. PHP配置：通过php.ini文件调整PHP运行时参数

这种分离的设计使得Web服务器配置和PHP运行时配置可以独立管理，提高了系统的可维护性。

Caddyfile配置详解

基础配置示例

最基本的Caddyfile配置只需几行即可启动PHP服务：

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

全局配置选项

FrankenPHP提供了丰富的全局配置选项：

{
    frankenphp {
        num_threads 8      # 初始PHP线程数，默认为CPU核心数的2倍
        max_threads 16     # 最大PHP线程数，默认为num_threads值
        max_wait_time 10s  # 请求等待PHP线程的最大时间
        
        # 设置PHP ini参数
        php_ini memory_limit 256M
        php_ini max_execution_time 30
        
        # Worker配置
        worker {
            file /path/to/worker.php
            num 4
            env APP_ENV production
            watch /path/to/watch
            name my_worker
        }
    }
}

Worker机制深入解析

Worker是FrankenPHP的核心概念之一，它允许PHP应用保持常驻内存，大幅提升性能。配置Worker时需要注意：

1. 文件监控：在开发环境中，可以使用watch指令实现代码热更新
2. 环境隔离：每个Worker可以有自己的环境变量配置
3. 资源分配：可根据应用需求分配不同数量的线程

多Worker配置示例：

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

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

文件监控高级配置

文件监控是开发环境中的实用功能，支持多种匹配模式：

worker {
    file /app/public/worker.php
    watch /app/**/*.php      # 监控所有PHP文件
    watch /app/**/*.{twig,yml} # 监控Twig和YAML文件
    watch /app/config        # 监控整个config目录
}

注意事项：

• 避免监控运行时生成的文件（如日志）
• 复杂的监控模式可能影响性能
• 生产环境通常不需要文件监控

PHP配置体系

配置文件位置

根据安装方式不同，PHP配置文件的位置有所差异：

1. Docker安装：

   • 主配置：/usr/local/etc/php/php.ini
   • 扩展配置：/usr/local/etc/php/conf.d/
   • 扩展目录：/usr/local/lib/php/extensions/

2. RPM/Debian包安装：

   • 主配置：/etc/frankenphp/php.ini
   • 扩展配置：/etc/frankenphp/php.d/
   • 扩展目录：/usr/lib/frankenphp/modules/

3. 静态二进制：

   • 搜索顺序：当前目录 → /etc/frankenphp/php.ini
   • 注意：静态二进制无法动态加载扩展

配置方式

除了传统的php.ini文件，FrankenPHP还提供多种配置方式：

1. 环境变量：

   PHP_INI_SCAN_DIR=/path/to/ini/files
   

2. Caddyfile内联配置：

   frankenphp {
       php_ini {
           memory_limit 256M
           max_execution_time 30
       }
   }
   

3. 多配置文件：可以通过include方式组织复杂的配置

高级特性配置

全双工模式(HTTP/1)

对于需要双向通信的场景（如WebSocket），可以启用全双工模式：

{
    servers {
        enable_full_duplex
    }
}

注意事项：

• 可能导致不支持此特性的旧客户端死锁
• 更适合现代浏览器环境

调试模式

在Docker环境中启用调试模式：

docker run -e CADDY_GLOBAL_OPTIONS=debug ...

调试模式会输出更详细的日志信息，适合开发排错。

最佳实践建议

1. 生产环境配置：

   • 使用专用的php.ini-production配置
   • 合理设置线程数（通常为CPU核心数的1.5-2倍）
   • 禁用文件监控

2. 开发环境配置：

   • 使用php.ini-development配置
   • 启用文件监控
   • 可以启用调试模式

3. 性能调优：

   • 根据应用特点调整worker数量
   • 监控线程使用情况优化max_threads
   • 考虑启用OPcache等PHP性能优化工具

常见问题解答

Q: 修改配置后如何生效？ A: 对于Caddyfile配置，需要重启FrankenPHP；对于PHP配置，取决于具体参数，部分参数支持运行时重载。

Q: 如何知道当前生效的配置？ A: 可以创建一个phpinfo()页面查看，或使用FrankenPHP的日志功能。

Q: 多应用如何共享配置？ A: 可以通过全局配置块定义共享配置，然后在各站点配置中引用。

通过本文的详细讲解，开发者应该能够全面掌握FrankenPHP的配置方法，根据实际需求灵活调整各项参数，充分发挥FrankenPHP的性能优势。

frankenphp The modern PHP app server 项目地址: https://gitcode.com/gh_mirrors/fr/frankenphp