FrankenPHP 快速上手指南：安装、运行与现代 PHP 应用服务器入门-开发者社区

FrankenPHP 快速上手指南：安装、运行与现代 PHP 应用服务器入门

【免费下载链接】frankenphp🧟 The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp

本文基于仓库中的俄语版项目主页（docs/ru/README.md）整理成文，并结合仓库源码与配置对关键命令和实现细节进行扩充。FrankenPHP 是一个构建在 Caddy Web 服务器之上的现代 PHP 应用服务器，本文介绍其核心特性、全平台安装方式、基础使用方法（php-server、php-cli、systemd 服务），并顺带梳理配置入口与文档导航，帮助读者在 10 分钟内完成从零到可运行的 PHP 应用部署。

什么是 FrankenPHP

FrankenPHP 是一个现代 PHP 应用服务器，底层基于 Caddy Web 服务器构建。它不是一个普通的 PHP 运行环境，而是将 PHP 直接以 SAPI 形式嵌入 Go 编写的服务器进程，为 PHP 应用带来一系列"超能力"：

Early Hints（HTTP 103 状态码）：在完整响应生成前提前推送资源提示，显著降低首屏等待时间；
Worker 模式：PHP 应用常驻内存，请求无需重复初始化框架与容器，官方针对 Laravel 和 Symfony 提供了开箱即用的集成；
Real-time 能力（内置 Mercure 协议集线器）：支持 Server-Sent Events（SSE）等实时推送场景；
自动 HTTPS：借助 Caddy 内置的证书管理能力，自动申请、续期 TLS 证书；
HTTP/2 与 HTTP/3 支持：现代传输协议开箱即用；
热重载（hot reload）：文件变更时自动重启 Worker，详见 docs/ru/hot-reload.md。

从源码结构可以印证这一架构：仓库根目录的 caddy/frankenphp/main.go 是 FrankenPHP 的入口，它导入了 Caddy 标准模块、frankenphp/caddy模块以及 Mercure、Vulcain 模块，然后调用caddycmd.Main()启动整个服务器。也就是说，FrankenPHP 本质上是"一个内置了 PHP 运行时与众多增强模块的 Caddy 发行版"。

此外，FrankenPHP 还可以作为独立的 Go 库使用：通过net/http标准接口，将 PHP 嵌入任意 Go 应用中。仓库根目录的 frankenphp.go 正是这个库的核心包（package frankenphp），其包注释明确说明它既可以支撑 FrankenPHP 应用服务器本身，也可以被任何 Go 程序复用。

FrankenPHP 兼容任何 PHP 应用，无需改动业务代码即可运行；对于 Laravel、Symfony 等项目，配合 Worker 模式可获得显著的性能提升。

开始之前：平台说明

在 Windows 上运行 FrankenPHP，官方建议使用WSL（Windows Subsystem for Linux）环境，这与 Linux/macOS 下的安装与使用方式保持一致。

安装 FrankenPHP

1. 一键安装脚本（Linux / macOS）

复制以下命令到终端执行，脚本会自动为当前平台选择并安装合适的版本：

curl https://frankenphp.dev/install.sh | sh

这是最快捷的安装方式，适合快速体验。

2. 独立静态二进制文件

如果不想依赖 Docker 或其他包管理器，官方提供 Linux 与 macOS 的独立二进制发行版，内置PHP 8.4运行时以及大多数流行的 PHP 扩展（例如 opcache、intl、pcntl 等）。Linux 二进制为静态链接，无需安装任何系统依赖即可在任何发行版上运行。

下载地址：官方 Releases 页面（仓库根目录 README.md 中提供了对应入口）。
扩展安装限制：最常见的扩展已内置其中，但无法再向静态二进制中追加安装额外扩展。

3. rpm 包（dnf 系发行版）

官方维护者提供适用于所有使用dnf的系统的 rpm 包。安装步骤如下：

sudo dnf install https://rpm.henderkes.com/static-php-1-0.noarch.rpm sudo dnf module enable php-zts:static-8.4 # 可选 8.2–8.5 sudo dnf install frankenphp

安装扩展：

sudo dnf install php-zts-<extension>

对于默认源中没有的扩展，可以使用 PIE（PHP 扩展安装器）：

sudo dnf install pie-zts sudo pie-zts install asgrim/example-pie-extension

4. deb 包（apt 系发行版）

官方维护者提供适用于所有使用apt的系统的 deb 包。首先添加仓库并导入签名密钥：

sudo curl -fsSL https://key.henderkes.com/static-php.gpg -o /usr/share/keyrings/static-php.gpg && \ echo "deb [signed-by=/usr/share/keyrings/static-php.gpg] https://deb.henderkes.com/ stable main" | sudo tee /etc/apt/sources.list.d/static-php.list && \ sudo apt update sudo apt install frankenphp

安装扩展：sudo apt install php-zts-<extension>

对于默认源中没有的扩展，同样使用 PIE：

sudo apt install pie-zts sudo pie-zts install asgrim/example-pie-extension

5. Docker

Docker 镜像是目前最流行的运行方式之一，一条命令即可启动：

docker run -v .:/app/public \ -p 80:80 -p 443:443 -p 443:443/udp \ dunglas/frankenphp

将当前目录挂载到容器的/app/public（即站点的文档根目录），映射 80/443 端口（443/udp用于 HTTP/3），然后访问https://localhost即可。

[!TIP]不要使用https://127.0.0.1，请使用https://localhost并接受自签名证书。若要更换域名，可通过设置环境变量SERVER_NAME实现，详见 docs/ru/config.md 的环境变量一节。

关于 Docker 镜像的更多用法（自定义扩展、版本选择、生产部署），可阅读 docs/ru/docker.md。

6. Homebrew（macOS / Linux）

FrankenPHP 以 Homebrew 软件包形式提供：

brew install dunglas/frankenphp/frankenphp

安装扩展：使用 PIE（brew install pie后通过pie命令安装）。

使用 FrankenPHP

启动一个 PHP 服务器

在包含 PHP 应用的目录中执行：

frankenphp php-server

该命令会以当前目录为站点根目录，启动一个生产可用的 PHP 服务器（同时提供静态文件服务）。

从源码看，php-server子命令在 caddy/php-server.go 中注册，它支持以下实用参数：

参数	短选项	说明
`--domain=<example.com>`	`-d`	指定域名；使用公共域名时需先配置好 A/AAAA 记录，服务将自动启用 HTTPS（监听 443 端口）
`--root=<path>`	`-r`	站点根目录，默认当前目录
`--listen=<addr>`	`-l`	自定义监听地址；未指定且无域名时默认`:80`
`--worker=/path/to/worker.php<,nb-workers>`	`-w`	启用 Worker 模式的入口脚本，可指定线程数量
`--watch[=<glob-pattern>]`	无	文件变更监听，用于开发环境自动重启 Worker
`--access-log`	`-a`	开启访问日志
`--debug`	`-v`	输出详细的调试日志
`--mercure`	`-m`	启用内置的 Mercure.rocks 实时推送集线器
`--no-compress`	无	禁用 Zstandard、Brotli 与 Gzip 压缩

例如，带 Worker 模式与访问日志的启动方式：

frankenphp php-server --worker=public/index.php,8 --access-log

运行 PHP CLI 脚本

FrankenPHP 可以直接执行命令行 PHP 脚本，行为类似于 PHP CLI SAPI：

frankenphp php-cli /path/to/your/script.php

该命令实现在 caddy/php-cli.go 中：它调用 cli.go 的ExecuteScriptCLI()函数，经由 C 桥接（frankenphp_execute_script_cli）执行脚本并返回退出状态码。因此php-cli可以无缝替代日常的php script.php工作流，例如运行 artisan、symfony console 或 Composer 脚本。

以 systemd 服务运行（deb / rpm）

通过 deb 或 rpm 包安装后，可以注册为系统服务并开机自启：

sudo systemctl start frankenphp

仓库的 package/debian/frankenphp.service 与 package/rhel/frankenphp.service 提供了 systemd 单元文件的参考实现，生产环境可在此基础上调整。

配置：从命令行到 Caddyfile

php-server适合快速启动与演示，而完整的生产配置则需要使用 Caddyfile。FrankenPHP 沿用了 Caddy 的配置体系，支持 Caddyfile、JSON 等格式，默认从当前目录加载Caddyfile，也可用-c/--config指定路径。

官方在 Docker 镜像与发行版中内置了一份开箱即用的 caddy/frankenphp/Caddyfile，它通过环境变量注入配置，是理解 FrankenPHP 配置的最佳起点：

{ skip_install_trust {$CADDY_GLOBAL_OPTIONS} frankenphp { {$FRANKENPHP_CONFIG} } } {$CADDY_EXTRA_CONFIG} {$SERVER_NAME:localhost} { root {$SERVER_ROOT:public/} encode zstd br gzip {$CADDY_SERVER_EXTRA_DIRECTIVES} php_server { #worker /path/to/your/worker.php } } import Caddyfile.d/*.caddyfile

其中：

SERVER_NAME：修改监听地址（默认localhost），同时影响 TLS 证书的签发域名；
SERVER_ROOT：站点根目录，默认public/；
CADDY_GLOBAL_OPTIONS：注入 Caddy 全局选项（如debug）；
FRANKENPHP_CONFIG：注入frankenphp指令下的配置（如worker、max_requests等）；
Caddyfile.d/*.caddyfile：自动加载的附加站点配置。

php_server指令的完整参数（root、split_path、resolve_root_symlink、env、file_server off、嵌套worker块等），以及全局frankenphp选项（num_threads、max_threads、max_wait_time、max_idle_time、max_requests、php_ini、worker），请查阅完整的俄文配置文档 docs/ru/config.md。那里还覆盖了watch文件监听、Worker 路径匹配（match）、按请求数重启线程（max_requests）、PHP_INI_SCAN_DIR与php_ini指令、关闭 HTTPS、HTTP/1 全双工、Shell 命令自动补全等进阶主题。

架构速览：为什么它"快"

从仓库源码可以勾勒出 FrankenPHP 的技术骨架：

入口统一：caddy/frankenphp/main.go 将 Caddy 标准模块、FrankenPHP 模块、Mercure 模块、Vulcain 模块一起编译进同一个二进制，最终调用 Caddy 命令行框架启动。
请求路由：caddy/php-server.go 展示了php-server生成的路由管线：目录规范重定向（308）→ 重写到index.php→ 匹配*.php请求交给php处理器 → 其余交给file_server，最外层可选叠加encode压缩与 Mercure 路由。这与 Caddyfile 中php_server指令的展开逻辑（route块）完全一致。
PHP 线程模型：FrankenPHP 维护一组常驻 PHP 线程（默认数量为 CPU 核数的 2 倍），通过num_threads/max_threads/max_idle_time等选项进行伸缩控制，Worker 模式下应用代码常驻内存，省去每次请求的框架初始化开销。

文档导航与生态示例

核心功能：Worker 模式见 docs/ru/worker.md，Early Hints 见 docs/ru/early-hints.md，Real-time 见 docs/ru/mercure.md
配置与部署：docs/ru/config.md、docs/ru/docker.md、docs/ru/production.md、docs/ru/performance.md
构建与嵌入：独立应用打包见 docs/ru/embed.md，静态二进制见 docs/ru/static.md，源码编译见 docs/ru/compile.md
框架集成：Laravel 见 docs/ru/laravel.md，Symfony 见 docs/symfony.md，WordPress 见 docs/wordpress.md
已知问题：docs/ru/known-issues.md
内部架构总览（英文）：docs/internals.md

社区中还活跃着大量基于 FrankenPHP 的项目骨架，覆盖 Sulu、Drupal、Joomla、TYPO3、API Platform 等生态；仓库根目录 README.md 中列出了完整清单，可作为选型参考。

总结

FrankenPHP 将 Caddy 的生产级 Web 服务器能力与常驻内存的 PHP 运行时合二为一：一条php-server命令即可得到带自动 HTTPS、HTTP/2/3、压缩与 Worker 模式的完整服务器；php-cli则无缝衔接命令行工作流；deb/rpm/Docker/Homebrew 多通道安装让各平台用户都能快速上手。若需深入生产级调优，请以 docs/ru/config.md 与 docs/ru/worker.md 为下一站继续探索。

【免费下载链接】frankenphp🧟 The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考