FrankenPHP实践：Caddy内置PHP，替代PHP-FPM的一体化部署方案

爱串门的老王·2026-09-23·阅读 23 GEO检测（免费）

FrankenPHPCaddyPHP-FPM

|难度：普通|阅读约 29 分钟

FrankenPHP实践：把PHP-FPM丢进Caddy之后，部署体验彻底变了

先交代背景。我是做PHP后端出身，这几年一直在折腾应用部署这摊事。以前每次上线一个PHP项目，流程基本是：装Nginx、装PHP-FPM、配fastcgi_pass、配进程管理、调超时、改socket权限，一套下来少说半小时，碰到多站点还要小心翼翼处理server block。后来接触了FrankenPHP，第一次跑起来的感觉就是：这玩意儿把PHP部署里最繁琐的那一层直接干掉了。它不是一个简单的实验项目，而是把Caddy的自动HTTPS、静态文件处理、反向代理能力，和PHP解释器整个揉进了同一个进程里。

如果你还没听过FrankenPHP，简单说：它是一款基于Caddy的现代化PHP应用服务器，PHP解释器直接内置在Caddy内部，不再需要单独的PHP-FPM进程。它支持worker模式（应用常驻内存）、原生HTTP/2和HTTP/3、自动签发续期Let's Encrypt证书，还能用Caddyfile一套配置搞定静态资源和PHP转发。这篇文章，我按自己的实践过程来写，从架构思路、安装、配置，到生产环境部署和踩坑记录，争取让读到的朋友少走弯路。

1. 为什么放弃Nginx + PHP-FPM：FrankenPHP的核心设计思路

1.1 传统PHP部署模式的痛点

传统的PHP部署架构，前端是Nginx，后面挂一个PHP-FPM服务，两者通过FastCGI协议通信。这套架构用了十几年，稳定性没什么问题，但麻烦事不少。首先是两层服务要分别维护，Nginx有一套配置语法，PHP-FPM又有自己的php.ini、pool配置，出了问题要两头查日志。其次是性能上，每个PHP请求进来，PHP-FPM都要重新初始化脚本环境、加载opcache、执行代码，请求一多就暴露瓶颈。

更麻烦的是，Nginx和PHP-FPM之间的通信，要么用TCP端口，要么用Unix Socket。TCP多了一层网络开销，Unix Socket虽然快一些，但权限配置、socket文件路径、超时设置这些细节，一旦没弄对，线上就出现502、504。对一个需要频繁发布、多环境部署的团队来说，这一整套链路维护成本不低。

1.2 FrankenPHP“一个进程搞定一切”的独到之处

FrankenPHP的设计思路是把Caddy作为Web服务器，直接把PHP解释器编译进去，省掉了外部PHP-FPM。这意味着什么？你的机器上只要跑一个二进制文件，它同时负责接收HTTP请求、处理静态文件、编译执行PHP脚本、管理HTTPS证书。整个技术栈从“Nginx + PHP-FPM + certbot + 定时续期任务”缩减成了“FrankenPHP单进程”。

这带来的好处，第一是部署复杂度直线下降。Caddy本身就以配置简单出名，一个Caddyfile几行就能搞定站点配置，自动HTTPS更是不用操心证书问题。第二是性能提升，特别是worker模式下，PHP脚本常驻内存，请求进来直接执行，不需要重新初始化框架、重新连接数据库，吞吐量提升非常明显。第三是配置一致性，所有规则（路由、静态缓存、反向代理、PHP执行）都写在同一个Caddyfile里，心智负担少了很多。

1.3 官方宣称的基准数据背后，实际体验如何

FrankenPHP官方页面给了个benchmark数据，说worker模式比传统PHP-FPM快好几倍。我自己的实测没有跑那么极限，但确实能感受到差异。用一个Laravel接口做压力测试，PHP-FPM模式下QPS大概在400左右，切到FrankenPHP worker模式，同样机器配置能跑到1000多，内存占用还更稳定。这个提升在我来看，主要来自两块：一是省掉了FastCGI通信和进程反复fork的开销，二是worker常驻内存后，框架初始化、服务容器构建、配置加载这些耗时操作只需要在worker启动时做一次。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 环境准备与安装：从官方包到Docker镜像的选择

2.1 推荐的生产环境安装方式

FrankenPHP官方提供两种主流安装方式：二进制文件和Docker镜像。二进制文件适合直接部署在物理机或云服务器上；Docker镜像则更适合在Kubernetes、Swarm这类容器环境里跑。我个人的建议是，如果你不是已经重度使用容器编排，优先选择二进制文件。理由很简单：少一层抽象就少一类问题，而且FrankenPHP本身就是静态编译的单文件，拷贝到服务器上就能执行，迁移成本极低。

安装二进制文件，最简单的是用官方的一键脚本：

bash复制curl -sSL https://frankenphp.dev/install.sh | sh

这个脚本会下载最新的release包，放到当前目录。之后把它移动到/usr/local/bin/frankenphp，就可以在任意目录下启动了。

注意：一键脚本拿到的二进制默认不包含某些扩展，比如Redis、AMQP这类。如果你项目里用到这些，建议先看后面的“自定义编译”部分。

2.2 自定义编译：哪些扩展值得自己加进去

FrankenPHP的Docker镜像提供了frankenphp:builder这个构建镜像，官方用它来编译带扩展的版本。你可以在Dockerfile里通过install-php-extensions这个工具快速添加你需要的PHP扩展。这里提几个常见的：

pdo_mysql、mysqli：连MySQL必备。
redis：用了Redis做缓存、队列的话必须加。
opcache：生产环境强烈建议开，编译时带上，运行时再把配置打开。
intl：Laravel、Symfony这类框架在某些场景下会需要。

举个例子，我编译生产镜像的Dockerfile大概是这样的：

dockerfile复制FROM dunglas/frankenphp:builder AS builder

RUN install-php-extensions pdo_mysql redis intl opcache

FROM dunglas/frankenphp:latest

COPY --from=builder /usr/local/lib/php/extensions/ /usr/local/lib/php/extensions/

这样构建出来的镜像，既保留了FrankenPHP的核心能力，又带上了项目所需的扩展。如果你直接用官方latest镜像装PHP应用，遇到“class not found”之类的问题，十有八九就是扩展缺失。

2.3 用Docker Compose快速起一个可运行环境

对于本地开发，Docker Compose是最快的方式。我本地常用的一套配置是这样的：

yaml复制services:
  frankenphp:
    image: dunglas/frankenphp:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - .:/app
      - caddy_data:/data
      - caddy_config:/config
    environment:
      - SERVER_NAME=localhost
    restart: unless-stopped

volumes:
  caddy_data:
  caddy_config:

把项目代码挂载到/app目录，通过SERVER_NAME=localhost告诉Caddy当前的站点域名。这个配置在本地跑起来，浏览器访问http://localhost就直接进到Laravel或ThinkPHP的入口文件了，不需要再配任何虚拟主机。

3. Caddyfile配置详解：路由、PHP执行与自动HTTPS一网打尽

3.1 最简配置：一个入口一个root

Caddyfile是FrankenPHP的配置核心。一个最简单的PHP站点配置是：

code复制localhost {
    root * /app/public
    php_server
}

第一行localhost是站点域名；root指定网站根目录；php_server是FrankenPHP提供的指令，它做了几件重要的事：识别.php文件并由内置PHP解释器执行；非PHP的静态文件直接由Caddy做静态响应；将所有未匹配的请求重写到index.php——也就是说，它相当于Nginx配置里的try_files $uri $uri/ /index.php?$query_string。

提示：php_server是FrankenPHP对Caddy官方php_fastcgi指令的一次封装。它的设计意图就是覆盖90%以上的PHP应用场景，如果你不需要自定义rewrite规则，直接用php_server就够了。

3.2 多站点配置与路径重写

多站点场景下，Caddyfile里可以并列写多个站点块：

code复制example.com {
    root * /sites/example/public
    php_server
}

api.example.com {
    root * /sites/api/public
    php_server
}

需要自定义路由规则时，可以用Caddy原生的handle和route指令。比如某些API路径要单独处理，不经过PHP：

code复制example.com {
    root * /sites/example/public
    route {
        /healthz {
            respond "OK" 200
        }
        /* {
            php_server
        }
    }
}

这段配置里，/healthz直接返回“OK”，不进入PHP环境，其他所有请求交给php_server处理。这样做的意义在于，健康检查、静态文件、PHP动态请求可以在同一套配置里分层处理，不需要像Nginx那样写一堆location块。

3.3 自动HTTPS与本地开发环境的证书策略

Caddy最出圈的功能就是自动HTTPS。它默认情况下，只要配置了真实域名且80和443端口可访问，就会自动向Let's Encrypt申请证书，到期前自动续期。对生产环境来说，这个功能意味着你不需要再维护certbot、不需要自己写cron续期脚本，证书整个生命周期都交给FrankenPHP。

本地开发时，如果没有真实域名，可以在SERVER_NAME环境变量里指定localhost，Caddy会自己生成一个本地CA证书，如果你的系统信任了Caddy的本地CA，浏览器访问https://localhost就不会报警告。这一步对开发体验的提升很明显，不用再为“本地是http、线上是https”的差异去写两套环境配置。

bash复制SERVER_NAME=localhost:443 frankenphp run

4. Worker模式深入解析：从“请求驱动”到“常驻内存”

4.1 worker模式到底改了什么

传统PHP-FPM模式下，每个请求进来，PHP都会经历一次完整的生命周期：加载扩展、读取opcache缓存、执行脚本、释放所有资源。虽然opcache能省掉编译这一步，但框架本身的初始化开销是省不掉的。Laravel这种重框架，单次请求可能要用50-100ms来构建容器、加载服务提供者、解析路由，这部分开销几乎每个请求都在重复。

FrankenPHP的worker模式，核心做法是在进程启动时预加载一次PHP脚本，然后让这个脚本常驻内存监听请求。它复用函数和类定义、复用框架的全局容器、复用已建立的数据库连接，请求到达时直接执行控制器逻辑，响应结束后不销毁对象。用一句话概括：PHP应用从“用完即走”变成了“启而不停”。

4.2 worker模式的开启方法与参数调优

在Caddyfile里开启worker模式很简单，php_server后面加一个worker参数：

code复制localhost {
    root * /app/public
    php_server {
        worker /app/public/index.php
        max_requests 500
        max_worker_conns 16
    }
}

worker指定的是worker脚本路径，对于Laravel、Symfony这类基于front controller的应用，直接指向public/index.php即可。max_requests是指worker处理多少个请求后自动重启，设这个参数的目的，是为了防止长时间运行导致的潜在内存泄漏。max_worker_conns是worker连接数的上限，决定了一个worker可以同时处理多少个并发请求。

注意：worker模式和某些一次性长生命周期任务（比如pcntl_fork、高内存消耗的shell命令）存在兼容性问题。如果你代码里有pcntl_fork相关内容，用worker模式时要格外谨慎，建议先做好压测再上线。

4.3 worker模式对主流框架的兼容性实测

我自己在Laravel 10和ThinkPHP 8.0上都跑过worker模式。Laravel 10官方对FrankenPHP的支持已经写进了文档，实测下来没遇到什么坑，唯一要注意的是把octane之类的常驻内存增强包关掉，不要让两条常驻链路打架。ThinkPHP 8.0因为是国内重度使用的框架，我也验证过，启动后跑接口、跑队列都没问题，只是首次启动时比较慢，因为要预编译、预加载大量类文件，大概需要5-8秒，之后就会很稳定。

如果你用的是Swoole常驻内存方案，切换过来反而要改一些代码，因为Swoole和FrankenPHP的worker模式虽然都是常驻内存，但底层API不同，协程、监听器等机制也不一样。没有特殊原因，不建议在同一个项目里混合使用这两套方案。

5. 生产部署实践：Systemd托管、进程守护与日志管理

5.1 写一个可用的Systemd Service

生产环境我一般用systemd来托管FrankenPHP进程。这里给一份我实际在用的service配置：

ini复制[Unit]
Description=FrankenPHP PHP Application Server
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/sites/example
Environment=SERVER_NAME=example.com
EnvironmentFile=/etc/frankenphp.env
ExecStart=/usr/local/bin/frankenphp run --config /etc/frankenphp/Caddyfile
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

几个细节说一下。Type=simple适合FrankenPHP这种前台运行的进程；Restart=always保证进程意外退出后自动拉起；EnvironmentFile用来统一管理环境变量，证书配置、域名、站点路径都放这里，切换环境时只需改这一个文件。

启动服务的命令：

bash复制sudo systemctl daemon-reload
sudo systemctl enable frankenphp
sudo systemctl start frankenphp

5.2 日志轮转与关键字监控

FrankenPHP的日志默认输出到标准输出，由systemd接管并写入journal。长期跑下来，journal文件会越来越大，所以日志轮转得配上。可以在/etc/logrotate.d/frankenphp里写：

conf复制/var/log/frankenphp.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    create 0640 www-data www-data
}

同时，在Caddyfile里可以给日志增加关键字过滤和输出配置。比如只记录5xx错误和panic信息：

code复制log {
    output file /var/log/frankenphp.log
    level WARN
}

生产上我还会用journalctl -u frankenphp -f来实时盯日志，排查问题时配合grep按时间、按关键字过滤。

5.3 进程数、内存上限与连接数调优参考

在传统PHP-FPM里，我们要关心pm.max_children、pm.start_servers这些参数。FrankenPHP里，和性能相关的几个关键点如下：

max_worker_conns：控制单个worker的并发连接数，设置太高会导致MySQL连接数被打满，一般8到16比较合适。
PHP的memory_limit：通过php.ini设置，生产环境建议256M起步，要根据实际业务峰值来调。
Caddy的server_tokens：默认隐藏版本号，不用刻意改。

我的经验是，先用默认配置跑，然后用压测工具（比如wrk、ab）找到当前配置下的瓶颈，再看是CPU、内存还是数据库连接数先到顶，然后做对应的单点调整。FrankenPHP的参数不像PHP-FPM那么多，优化起来反而更轻松，因为大部分资源管理都由内部完成了。

6. 常见问题与排查技巧：那些让我熬夜的坑

6.1 端口被占用、权限不够这类起步问题

症状一：80端口被Nginx占用，FrankenPHP启动失败。

这几乎是迁移过程中必踩的坑。解决方式很简单，先停掉Nginx：

bash复制sudo systemctl stop nginx
sudo systemctl disable nginx

然后确认端口释放：sudo ss -lntp | grep :80。如果机器上还有其他服务占用了80/443端口，可以在Caddyfile里改用其他端口，或者干脆用iptables做转发。

症状二：无法写入.acme.sh证书目录或Caddy数据目录。

caddy_data和caddy_config这两个目录需要给到运行FrankenPHP的用户写权限。如果是用www-data运行，提前执行：

bash复制sudo mkdir -p /data/caddy
sudo chown -R www-data:www-data /data/caddy

6.2 worker模式下的典型异常与调试方法

症状一：代码改了，线上不生效。

这是worker模式的典型问题。因为worker常驻内存，代码文件如果被修改，worker里的类定义和函数定义不会跟着刷新。解决办法就是在部署流程里，把代码更新之后自动重启FrankenPHP：

bash复制sudo systemctl restart frankenphp

症状二：某些请求偶发性500错误，日志里有Segmentation fault。

这种情况多半是PHP扩展和worker模式不兼容导致的。排查方法是先用非worker模式（去掉worker参数）跑一段时间，看问题是否消失。如果确认是worker模式触发，再逐个禁用可疑扩展来定位。

6.3 回顾：FrankenPHP到底适合哪些项目

如果你问我现在迁移值不值，我的建议是分情况。

纯PHP项目、Laravel/Symfony/ThinkPHP这类现代框架项目，FrankenPHP很适合，部署体验和运行性能都有明显提升。但如果你用了一些和PHP-FPM强绑定的老项目，比如依赖$_SERVER['SCRIPT_FILENAME']这种变量的、或者用了大量pcntl_*函数的，迁移成本会高一些，建议先在测试环境充分验证。

另外，我自己在实际使用中有个体会：FrankenPHP并不是单纯地“替代Nginx + PHP-FPM”，它更像是对整个PHP部署方式的一次重构。当PHP解释器、Web服务器、自动HTTPS证书管理、静态文件处理全部收拢到一个二进制文件里，运维的复杂度下降了不止一个量级。尤其是对于个人开发者或小团队，能把精力从“维护服务器环境”挪到“写业务代码”上，这种感觉是挺明显的。

最后再分享一个小技巧：如果你用的是Docker方式运行，记得把composer install的步骤放在构建镜像时完成，不要把vendor目录挂载到宿主机上，否则每次启动都可能因为依赖差异导致诡异报错。这个坑我踩过一次，后来查了很久才发现是挂载导致vendor不一致。