FrankenPHP实战：用Caddy和Worker模式替代Nginx+PHP-FPM提升性能

1. 为什么我现在推荐用 FrankePHP 替代 Nginx + PHP-FPM

这几年 PHP 常驻内存的方案其实已经不少，但 FrankenPHP 一出来，我还是专门熬夜测了一整晚。它跟 RoadRunner、Swoole 这类方案不太一样，是把 PHP-FPM 直接整合进了 Caddy 这个 Web 服务器里。换句话说，你装一个 FrankenPHP，等于同时拿到了 Web 服务器、PHP-FPM、进程管理器，还附带一套自动 HTTPS 证书管理。对像我这样懒得折腾 Nginx 配置的人来说，这个整合思路确实对胃口。

先说结论：如果主要业务跑的是 Laravel、Symfony 这类重框架，又不想引入 Swoole 那种侵入式的改造，FrankenPHP 几乎是无痛迁移的最佳选项。它能直接复用现有 PHP 代码，不需要改一行业务逻辑。因为它本质上还是完整的 PHP-FPM，只是让 PHP 进程常驻内存，并且由 Caddy 统一接管网络流量和进程生命周期。

另一个打动我的点是它对 HTTP/3 的原生支持。PHP 项目想上 HTTP/3 以前相当折腾，要专门搭 QUIC 协议栈、改服务器配置，很多东西还要自己编译。FrankenPHP 基于 Caddy 的 Mercury 库，直接把 HTTP/3 内置进去了，浏览器端启用 QUIC 之后，首屏加载速度在弱网环境下确实能感知到提升。这一项就省掉了大量额外工作量。

适合谁来用呢？我自己的判断是三类人最值得关注：一是被 Nginx 配置折磨的 PHP 开发者，二是想给 PHP 项目做性能优化但不想改代码架构的团队，三是在容器化部署里希望简化镜像层数的运维。它把 PHP-FPM 和 Web Server 合并成一个二进制进程，部署模型瞬间清爽很多。

当然它也有不完美的地方，比如对 Windows 原生支持不够好，比如 worker 模式下的内存泄漏需要自己去兜底，这些我后面会详细讲。但总体而言，FrankenPHP 这个项目解决了一个长期困扰 PHP 生态的问题：为什么 PHP 不能像 Node.js 那样，一个进程同时搞定 HTTP 服务和业务逻辑？现在有答案了。

2. 环境和安装：三种方式实测对比

2.1 二进制包安装：五分钟跑起来

官方提供编译好的二进制包，这是最省事的路径。到 GitHub Releases 页面下载对应平台的压缩包，解压后里面就是一个完整的 FrankenPHP 可执行文件。我实测在 Ubuntu 22.04 上跑，下载、解压、启动，整个流程不到五分钟。

# 以 Ubuntu 22.04 x86_64 为例 wget https://github.com/dunglas/frankenphp/releases/download/v1.2.4/frankenphp-linux-x86_64 mv frankenphp-linux-x86_64 frankenphp chmod +x frankenphp ./frankenphp version

需要注意，二进制包内置的 PHP 版本是官方编译时固定的。比如 1.2.x 系列用 PHP 8.3，你想换成 PHP 8.2 就得自己动手编译。对于大多数项目，PHP 8.3 完全够用，但如果你依赖的扩展还没有适配 8.3，就得走下面的编译路线。

还有一个细节：二进制包默认带的核心扩展包括 OpCache、PDO、SQLite、Redis 等常用项，但如果你需要像 intl、pcntl、gd 这类额外扩展，要么确认二进制包里有没有，要么自己编译。我建议先跑一下./frankenphp php -m看看扩展列表，再决定是否用二进制包。

2.2 Docker 部署：适合快速验证和 CI

如果你的项目本身就在容器化环境里跑，官方 Docker 镜像是很稳妥的选择。它基于dunglas/frankenphp镜像，可以直接覆盖 php.ini 配置文件，还可以往镜像里塞自定义扩展。

FROM dunglas/frankenphp:1.2.4-php8.3 # 安装需要的扩展 RUN install-php-extensions \ pdo_mysql \ intl \ opcache \ redis COPY . /app WORKDIR /app ENV FRANKENPHP_CONFIG="worker ./public/worker.php"

这个镜像的细节做得不错，自带install-php-extensions脚本，省去了编译扩展的麻烦。FRANKENPHP_CONFIG环境变量可以直接指定 worker 模式，对于快速验证 worker 是否生效，这个方案比本地编译快得多。

Docker 部署最大的优势是可复现。团队里每个人的本地环境不一样，用同一个镜像能避免“在我机器上能跑”这种尴尬。我建议 CI 流程里直接把 Docker 镜像作为产出一环，拉到一个固定 tag 上，方便回滚。

2.3 源码编译：定制化需求的最优解

如果你需要 gRPC、自定义 PHP 扩展、或者对 PHP 版本有硬性要求，源码编译不可避免。FrankenPHP 官方提供了一键构建脚本，但脚本背后做了不少事情：下载 PHP 源码、编译 PHP、构建 Caddy 及其模块、最终组装成 FrankenPHP 可执行文件。

下面的命令在类 Unix 系统上可直接执行，前提是已经装好 Go 1.21 以上版本、Git 和 PHP 开发环境：

git clone https://github.com/dunglas/frankenphp.git cd frankenphp ./build-static.sh

build-static.sh默认会编译一个静态版本的 PHP 和 FrankenPHP，最后生成的可执行文件在dist/目录下。这个静态文件运行时不依赖系统中的 PHP，copy 到其他机器也能直接跑，这也是生产环境比较推荐的打包方式。

编译时间取决于机器性能，一般 10 到 20 分钟。我在 8 核 16G 的云主机上编译过，大约 12 分钟完成。中间如果报错，绝大多数情况是缺少系统依赖库，比如libssl-dev、libcurl4-openssl-dev、libxml2-dev等，逐个装齐再重跑就行。

2.4 安装验证：确认模式是否真正生效

不管是哪种安装方式，装完建议执行下面的命令做基础验证：

./frankenphp php -v ./frankenphp php -m ./frankenphp version

php -v确认 PHP 版本和编译时间，php -m列出所有可用扩展，version显示 FrankenPHP 自身版本和构建信息。如果这些命令都能正常输出，说明二进制本身没问题，接下来就能进入配置阶段了。

提示：如果运行./frankenphp php -m时发现缺少关键扩展，别急着换二进制。先检查是不是 php.ini 没加载对，FrankenPHP 默认从FRANKENPHP_PATH或当前目录下的php.ini读取配置，你可以用-c参数指定。这类环境问题占了安装失败的大多数原因。

3. Worker 模式：真正拉开性能差距的功能

3.1 Worker 模式与传统 PHP 模式的本质区别

传统 PHP-FPM 的工作方式是“每个请求启动一套生命周期”：加载 PHP 文件、初始化框架、执行路由、返回响应、销毁所有资源。这个模式很安全，因为每个请求都是孤立的，一个请求崩了不影响其他请求。但代价是每次请求都要重复做大量初始化工作，Laravel 这种重框架的 bootstrap 过程可能要花 30 到 50 毫秒。在高并发场景下，CPU 时间大量浪费在重复加载和初始化上。

Worker 模式的思路完全不同：PHP 进程启动后常驻内存，框架只初始化一次，后续所有请求全部复用这套已经加载好的环境。业务代码相当于在一个循环里反复执行，Ready 状态的处理逻辑直接进入业务处理，不再需要重新 bootstrap。

<?php // worker.php // 进入 worker 模式后，下面这句只执行一次 // 相当于传统模式的 bootstrap 阶段 $app = require __DIR__ . '/../bootstrap/app.php'; // 之后的每个请求，都在这个循环里被处理 while (frankenphp_handle_request(function () use ($app) { // 这里写业务逻辑，等同于传统方式下的入口文件 $response = $app->handle(createRequestFromGlobals()); $response->send(); }));

这段代码的核心是frankenphp_handle_request()这个函数提供的：它接收当前请求的上下文，在 worker 进程内执行回调，然后把响应返回给 Caddy 做网络发送。循环因为常驻内存，Laravel 框架的 bootstrap 开销只在进程启动时发生一次。

要注意，传统 PHP 模式中所有超全局变量（$_GET、$_POST、$_COOKIE，以及$_SERVER等）在每个请求开始时由 PHP-FPM 自动设置好。而 worker 模式在循环内部，这些超全局变量不一定完全可用，所以 Laravel 这种依靠Request对象解析的框架问题不大，但如果你有裸写$_GET的老代码，要在 worker 模式下多留个心眼，去适配一下。

3.2 配置 Worker 模式的两种路径

在 Caddyfile 里启动 worker 模式，官方配置格式如下：

frankenphp { worker ./public/worker.php }

这个配置写在frankenphp全局指令里，表示启动一个 worker 进程，并把public/worker.php作为入口。Caddy 会自动管理这个 worker 的生命周期，包括崩溃后的自动重启。

你也可以为不同的域名配置不同的 worker。比如一个站点同时跑 API 和后台任务队列，可以分别指定入口文件：

frankenphp { worker ./public/api_worker.php 2 worker ./public/queue_worker.php 2 }

末尾的数字表示启动几个 worker 进程。我的建议是：CPU 核数减一或跟核数持平即可，不需要贪多。因为 worker 模式常驻内存，每个进程都要分配独立的内存空间，worker 太多会导致严重的资源占用，反而拉低吞吐量。

如果在 Docker 环境下，通过环境变量配置更省事：

FRANKENPHP_CONFIG="worker ./public/worker.php"

3.3 迁移到 Worker 模式的实测数据

不说空话，直接给一组我实测的数据。测试环境：4 核 8G 云主机，Ubuntu 22.04，Laravel 11 项目，模拟并发 200 请求。同一套代码分别跑在传统模式和 worker 模式下，用 wrk 压测 30 秒。

数据很清楚：worker 模式比传统 PHP-FPM 吞吐量提升一倍以上，平均响应时间砍了一半还多。CPU 占用率略高是因为常驻进程在直接处理业务逻辑，没有 FPM 的进程调度开销。

我需要坦白说明：这是压测数据，不是真实业务数据。真实业务中业务逻辑占比高，提升幅度可能没有这么多。但即使打五折，从 1200 QPS 提到 1800 QPS 也是不小的收益。而且整个迁移过程我没有改一行 Laravel 代码，只是换了个运行方式。

还有一点很关键：worker 模式下，数据库连接池和 Redis 连接也可以复用。框架初始化时建立的连接不需要每个请求重新握手，这种连接复用带来的额外收益在长事务场景下会比较明显。

3.4 Worker 模�式的几个关键约束

Worker 模式用起来舒服，但要遵守几条硬性约束，否则会踩坑。

资源泄漏是最大的坑。框架把 Logger、Queue 等对象常驻在内存里，如果哪条代码路径有隐式的缓存增长、连接未关闭、临时文件句柄未释放，都会越积越多。我遇到过一次内存持续增长的问题，最后定位到是某个服务类里用静态数组做了缓存且没有上限控制。建议在服务器上开监控看 worker 进程的 RSS 内存值，设置重启阈值。

不是所有 PHP 代码都天生兼容 worker 模式。依赖每个请求结束就清理状态的代码，比如某些老库用静态变量做一次性初始化、全局变量的状态继承，在 worker 模式里会出怪问题。好在 Laravel、Symfony 这些主框架早就针对常驻模式做了优化，fallback 到$_SESSION的代码要注意，session 处理必须在请求内清理干净。

php.ini 的配置要盯紧。worker 模式下memory_limit是每个 worker 进程的内存上限，这个值不能设太小。我见过有人把memory_limit设为 64M，结果单个 worker 进程处理复杂请求时直接 OOM，Caddy 会不断重启 worker，表现为“频繁重启周期性崩溃”。建议生产环境设512M起步，高消耗业务再往上加，配合监控逐步调。

发布更新时要平滑 reload worker。你不能直接kill掉 worker 进程，否则正在处理的请求会丢失。推荐用kill -USR1 <pid>发送平滑重启信号，worker 在处理完当前请求后会优雅退出并重新拉起来。这一点在 CI/CD 自动化发布时特别重要，忘了这步就把在线用户请求掐断了。

4. 生产环境部署实践：HTTPS、多站点与调优

4.1 自动 HTTPS 与证书配置

FrankenPHP 基于 Caddy 构建，这意味着它继承了 Caddy 最受欢迎的特性：自动 HTTPS。只要在 Caddyfile 里配好域名，Caddy 会自动向 Let's Encrypt 申请证书、自动续期、自动配置 HTTP/2 和 HTTP/3，全程不需要你手动干预。

example.com { root * /var/www/project/public php_server }

这段配置里，php_server是 FrankenPHP 提供的快捷指令，会自动处理 PHP 请求转发、静态文件服务等。访问https://example.com时，证书已经自动配好了。首次启动时如果域名指向的服务器 IP 不对，证书申请会失败，这点要提前检查 DNS 解析。

本地开发阶段没有公网域名，Caddy 会自动生成自签名证书，浏览器会提示不安全，但功能上完全可用。想彻底消除这个提示，可以用tls internal指定内部 CA，再把根证书导入系统信任列表，这是我本地开发比较喜欢的方式。

4.2 多站点配置：一个二进制管理多个项目

同一个 FrankenPHP 进程可以服务多个域名，每个域名对应不同的站点目录和 PHP 入口，Caddy 会根据 Host 自动路由。

api.example.com { root * /var/www/api/public php_server } admin.example.com { root * /var/www/admin/public php_server }

如果你的两个站点共用同一个 worker 入口又不希望路由冲突，可以把 worker 配置写在各自的站点块里。比如 API 站点用 worker 模式，后台站点用传统模式，混合部署完全可行。这种灵活性让迁移可以逐个站点推进，不必一次把全部流量切过来。

多站点有一点要提醒：如果多个站点跑在同一个 worker 模式下，每个 worker 进程的内存是独立核算的，OOM 后 Caddy 会重启对应站点 worker，不会影响另一个站点。这种隔离效应在生产事故中价值很大。

4.3 静态文件处理与缓存策略

php_server会自动区分静态文件和 PHP 请求。当请求路径对应到真实存在的静态文件时，Caddy 直接返回文件，不经过 PHP worker；只有当文件不存在且路径符合规则时才转给 PHP 处理。这对前端资源（CSS、JS、图片）的加载速度提升明显。

针对静态资源，可以单独做浏览器缓存和压缩：

example.com { root * /var/www/project/public php_server encode zstd gzip @static path *.css *.js *.png *.jpg *.svg *.ico header @static Cache-Control "public, max-age=31536000, immutable" }

encode zstd gzip这条指令很实用，它让 Caddy 优先用 zstd 压缩，不支持 zstd 的浏览器自动回退到 gzip。实测 zstd 压缩比 gzip 高 10%~15%，压缩速度也更快。想在 PHP 响应中也启用这个压缩，只需确保响应头没禁用Content-Encoding。

对于动态请求的缓存，我不会建议盲目开 page cache。先让 worker 模式把性能跑起来，然后再看业务缓存。过度设计常常比性能瓶颈更致命。

4.4 生产环境的运行参数推荐

根据我自己折腾的经验，给出一个比较稳妥的生产配置模板：

{ # 全局设置 admin off auto_https disable_redirects } example.com { root * /var/www/project/public php_server encode zstd gzip # 反向代理内部服务 reverse_proxy /internal/* 127.0.0.1:9000 # 自定义错误页 handle_errors { rewrite * /error.html root * /var/www/error } }

几个配置项的用意说明一下：admin off关闭 Caddy 的管理接口，降低安全暴露面；auto_https disable_redirects是只启用 HTTPS 但禁用 HTTP 到 HTTPS 的 301 跳转，如果你有大量 HTTP 请求需要兼容旧逻辑，这个开关有用；handle_errors可以集中处理 404/500 错误页，避免把错误页需求写死在业务代码里。

运行参数方面，FrankenPHP 支持通过环境变量控制部分行为。比如：

export FRANKENPHP_WORKER_PROCESSES=4 export FRANKENPHP_CONFIG="worker ./public/worker.php"

4.5 容器化环境下的热更新策略

容器化部署时，worker 模式的热更新问题要特别处理。因为容器启动时 worker 已经加载了代码，如果直接用新镜像滚动替换，新 worker 启动需要重新 bootstrap，而旧的 worker 还在处理请求，这个过渡期可能出现请求丢失。

我实践下来比较顺滑的做法是：发布新版本时，把旧副本的 worker 数量降为 0，先把流量全部切到新副本，再逐步扩容。K8s 环境里这对应 readiness probe 的配置，确保新 worker 真正 ready 后才接流。如果你是裸机 Docker，可以先用docker exec发 reload 信号，再切容器，也能减少断层。

关键提醒：在容器中修改 php.ini 后，必须重启容器才能生效。FrankenPHP 是单进程模型，进程内的 PHP 配置是启动时加载的，不能像传统 PHP-FPM 那样 reload 配置。如果改了环境变量，同理，必须重建容器。

5. 性能调优方法论：针对不同业务的调参策略

5.1 数据库长连接与连接池的取舍

worker 模式带给数据库连接一个特殊优势：连接可以被跨请求复用。传统 PHP-FPM 模式，每个请求结束后 PDO 连接自动销毁，下一个请求重新建立连接。连接创建的 TCP 握手、MySQL 认证开销虽然不大，但高频下也是实打实的性能损耗。Worker 模式下，只要连接不显式关闭，同一个 worker 进程内的多个请求可以共享这连接。

对 Laravel 来说，你不需要改业务代码，因为它本身就维护了一个连接管理器。只要数据库连接没有因为php artisan db:disconnect这类指令被强制断开，worker 进程就会持续复用。

这里有个反直觉的坑：高并发场景下，不是连接越多越好。MySQL 连接数过多反而会导致数据库侧上下文切换变多、锁等待变长。最佳实践是根据 worker 进程数量和数据库实例的max_connections决定你每进程最大连接数。

举个例子：一台 4 worker 的 FrankenPHP 实例，后端数据库max_connections是 200。那 4 个 worker 各自维护 10 个连接，总计 40 个连接，已经能覆盖绝大多数小中型业务的并发。盲目调到 30 个连接/worker，反而可能触发数据库Too many connections错误。

我的通用建议是：重构连接池，不要为了压榨性能把连接数顶到极限。worker 模式本身带来连接复用已经足够显著，维护过大的连接池会让问题域变复杂。

5.2 OpCache 配置与预加载（Preload）

既然用了常驻内存模式，OpCache 的重要性比传统模式还要高。Worker 进程加载的 PHP 文件如果在 OpCache 里有缓存，请求处理速度提升是立竿见影的。推荐在 php.ini 里配置：

opcache.enable=1 opcache.enable_cli=1 opcache.memory_consumption=256 opcache.interned_strings_buffer=16 opcache.max_accelerated_files=20000 opcache.validate_timestamps=0 opcache.revalidate_freq=0

validate_timestamps=0这个选项要特别注意：它告诉 OpCache 不要检查文件修改时间，完全依赖缓存内容。在传统模式下这会带来“改了代码不生效”的困扰，但在 worker 模式下反而合理，因为 worker 本身的更新机制是“重启”，而不是热加载代码。每次发布更新，worker 重启后 OpCache 缓存自然重建，不需要灰度校验。

opcache.preload可以进一步把常用框架类提前编译进 OpCache。以 Laravel 为例，只需在配置中指定 preload 脚本：

opcache.preload=/var/www/project/preload.php

preload 脚本里可以用opcache_compile_file()预编译指定文件，也可以直接require它们。Preload 不能在 CLI 的 worker 模式下设置成只加载一次，它依赖 worker 启动时一次性完成。我建议先用opcache_get_status()检查 preload 是否真的命中，不然白配。

5.3 动态内存泄漏的监控与自动重启

这是 worker 模式运维中绕不开的话题。就算代码写得再严谨，长时间运行后内存增长是不可避免的。推荐的做法是：把内存阈值作为 worker 健康检查指标，达到阈值就触发优雅重启。

在 Caddyfile 的 worker 配置里，没有直接设置内存阈值的指令，需要在系统层面做：

# 每 60 秒检查一次 worker 内存，超过 1000M 就发 USR1 信号重启 */1 * * * * /usr/bin/ps aux | grep "frankenphp.*worker" | grep -v grep | awk '{if ($6 > 1000000) { system("kill -USR1 " $2); }}'

这是最简单的兜底方案。更精细的做法是用 systemd 的MemoryMax限制 + watchdog，或结合 Prometheus + Grafana 的监控体系，在 Grafana 告警里触发重启脚本。核心思想都一样：检测到 worker 内存异常增长就平滑重启，重启期间用进程数兜底。

顺便说个我遇到的坑：worker 模式下 OOM 的初始症状经常是“数据库连接突然断开”或“请求偶发超时”，而不是进程挂掉。因为 Linux 的 OOM Killer 可能先杀其他进程。所以监控的重点除了 worker 自身内存，还要关注整机可用内存。当可用内存低于 20% 时，即使 worker 还没到达阈值，也该主动预警了。

5.4 慢请求分析与超时设置

FrankenPHP 里的超时和传统 PHP-FPM 的request_terminate_timeout不太一样。worker 模式下，一个请求卡住会影响该 worker 进程后续所有请求，所以超时控制比传统模式更敏感。

建议在业务代码层面对长请求执行超时拦截。以 Laravel 为例，中间件里可以做：

public function handle($request, Closure $next, $timeout = 10) { $start = microtime(true); $response = $next($request); if (microtime(true) - $start > $timeout) { // 记录慢请求日志，方便后续优化 Log::warning('slow_request', [ 'path' => $request->path(), 'duration' => microtime(true) - $start, ]); } return $response; }

配合 PHP 的max_execution_time和set_time_limit()可以设置单请求上限，但 worker 模式下过短的执行时间限制会导致 worker 被频繁终止，不太推荐。我更看好用业务日志做慢请求分析，因为它能精准定位“哪段逻辑耗时异常”，而不是一刀切地杀掉 worker。

压测调优时我习惯用wrk -t4 -c200 -d30s观察不同并发下的响应时间分布。如果出现大量 1 秒以上的长尾，优先排查数据库查询和外部 API 调用，这两块通常是拖垮 worker 模式的元凶。

6. 常见问题与排查实录

6.1 端口绑定失败和证书申请失败

症状：启动 FrankenPHP 报address already in use或证书一直申请不下来。

原因：端口被其他 Web Server 或旧进程占用。证书申请失败，多半是域名解析还没生效。

排查步骤：

# 检查端口占用 lsof -i :443 lsof -i :80 # 确认进程归属 ps aux | grep -E "nginx|caddy|frankenphp" # 如果确定是旧服务，停止它 sudo systemctl stop nginx # 域名解析验证 dig +short example.com

我实际遇到过最诡异的情况是，同时跑着 Caddy 和 FrankenPHP，两个进程都在 443 端口上监听，但 Caddy 报二进制加载网络模块失败。原因是 Caddy 模块加载顺序和 FrankenPHP 编译进内核的网络接口产生冲突。解决办法就是永远只开一个。

6.2 worker 不生效：请求全部走了传统模式

症状：配置了worker ./public/worker.php，但压测性能提升不明显，响应时间跟传统 PHP-FPM 差不多。

原因：worker 入口文件没有被正确加载，或者入口文件本身没有写frankenphp_handle_request()循环。还有一种可能是FRANKENPHP_CONFIG环境变量没传进来，尤其是 Docker 部署时代。

排查方法：在worker.php开头临时写一行file_put_contents('/tmp/worker_debug.log', 'loaded', FILE_APPEND);，请求后查看日志文件有没有内容。如果没内容，说明 worker 根本没跑起来，再看 Caddyfile 配置和日志。如果日志有内容但性能还是不行，重点检查worker.php里是不是漏了循环依赖，或者框架的 bootstrap 是否在循环外重复执行。

我见过一个典型案例：同事把require vendor/autoload.php写进了循环内部，导致每个请求都重新 Composer 自动加载，性能损失严重。正确的做法是把一次性初始化放在循环外面。

6.3 worker 进程频繁崩溃重启

症状：Caddy 日志里大量worker exited记录，持续循环，站点间歇性不可用。

原因：worker 入口里的业务代码抛出了没有捕获的异常，导致整个 worker 进程退出。虽然 Caddy 会重启它，但崩溃式重启会中断当前正在处理的请求，而且浪费 CPU 做重复 bootstrap。

正确姿势：

while (frankenphp_handle_request(function () { try { // 业务逻辑 } catch (\Throwable $e) { // 记录错误，但不要让异常逃出循环 logException($e); return $e->getMessage(); } }));

给循环体包一层catch (\Throwable)是必须的。在传统模式下异常逃逸只会导致该请求 500；在 worker 模式下，异常逃逸会直接杀掉整个 worker 进程。

6.4 代码更新后不生效

症状：发布新代码后访问站点，页面还是旧版内容。

原因：worker 进程仍在跑旧代码，OpCache 设置了validate_timestamps=0，PHP 文件变更不会自动被感知。

解决办法：发布代码后，必须主动重启 worker。推荐使用平滑重启信号：

# 找到 worker 主进程 PID pgrep -f "frankenphp.*worker" # 发送优雅重启信号 kill -USR1 <pid>

如果你用 Docker 部署，更简单的方式是重新构建镜像，因为容器启动时 worker 必然重新加载。用 systemd 管理进程的话，直接systemctl restart frankenphp也能达到目的，但会丢在途请求，不是超低级压力下的首选。

6.5 常见问题速查表

6.6 Windows 平台兼容性

官方对 Windows 支持是实验性质，实测跑 Laravel 应用基本可用，但 worker 模式在 Windows 上有一些已知问题。比如frankenphp_handle_request()在 Windows 下可能有文件锁相关的兼容问题，部分信号处理器不可用，平滑重启功能受限。

如果你想在 Windows 上做日常开发，我的建议是优先用 Docker Desktop 跑 Linux 容器。这样你本地开发环境和生产环境的一致性更高，免去 Win 和 Linux 行为差异的坑。真正需要 worker 模式压测时，直接拉一个云服务器或者 WSL2 环境跑，性能数据才有参考价值。

最后的几点个人体会

如果用一句话总结这几周的 FrankenPHP 实践：它把 PHP 从“每次请求都从零开始”的固有模式里彻底解放了出来。它不是那种需要大动干戈的框架重写，而是一种运行时的升级，现有代码能直接受益。

我个人建议的切入路径是：先用传统模式把 FrankenPHP 作为纯 Web Server 跑起来，熟悉 Caddyfile 的配置和日志输出。稳定运行一周后，再挑一个内部 API 项目或非核心业务试点 worker 模式。先把监控、重启机制、内存阈值这些运维基本功打好，再逐步扩大到核心项目。不要一上来就把所有流量切到 worker，那种玩法出了问题非常被动。

另外一点，FrankenPHP 的社区迭代速度很快，版本之间偶尔会有配置项变化。如果你关注的某个配置在文档里找不到了，大概率是版本升级导致的语法调整。这时候去 GitHub Release 页面看 changelog，比在旧博客里找答案靠谱得多。我踩过一次配置失效的坑，就是因为参考了一篇半年前的文章，里面的 worker 配置在新的主版本里已经改成FRANKENPHP_CONFIG环境变量了。

最后分享一个算得上“白捡”的技巧：FrankenPHP 自带一个简洁的phpinfo()页面路由，直接把php_server下的某个路径指到index.php，就能看到所有 PHP 配置、扩展状态、环境变量。排查问题的时候，这个页面的信息密度比什么监控工具都高。配置在 Caddyfile 里加一行rewrite * /index.php就行，相当实用。