FrankenPHP 入门指南：安装方式、使用命令与文档导航（基于 Caddy 的现代 PHP 应用服务器）
【免费下载链接】frankenphp🧟 The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp
本文以日语版项目首页文档 docs/ja/README.md 为骨架，结合仓库源码整理而成，介绍 FrankenPHP 的定位、多种安装途径、两种开箱即用的运行命令，以及官方文档体系的导航。
FrankenPHP 是一个构建在 Caddy Web 服务器之上的现代 PHP 应用服务器，核心目标是把 Caddy 的生产级 HTTP 能力与 PHP 运行时深度整合到一个可执行文件中。本文面向初次接触 FrankenPHP 的开发者，介绍它的核心特性、六种主流安装方式（安装脚本、静态二进制、rpm/deb 包、Docker、Homebrew）、基础使用命令（php-server与php-cli），并给出完整的官方文档导航，帮助读者快速选型、安装并启动第一个 PHP 应用。
一、FrankenPHP 是什么
从仓库根目录的 README.md 与日语版首页 docs/ja/README.md 可以看出，FrankenPHP 的核心定位如下：
- 基于 Caddy：FrankenPHP 直接复用 Caddy Web 服务器作为 HTTP 层，因此天然继承自动 HTTPS、HTTP/2、HTTP/3 等生产级能力，无需额外配置反向代理。
- 面向 PHP 应用：它可以承载任何 PHP 应用；通过官方文档所述的 Worker 模式官方集成，可以显著加速 Laravel、Symfony 等框架项目。
- 内置高级特性：包括 Early Hints（103 状态码）、Worker 模式、基于 Mercure 的实时功能、自动 HTTPS、HTTP/2、HTTP/3 等。
- 可作为 Go 库嵌入：FrankenPHP 同时是一个独立的 Go 库，允许你使用标准库
net/http将 PHP 嵌入任意 Go 应用。
从仓库结构看，其 Go 侧实现由根目录的 frankenphp.go、worker.go、threadworker.go、scaling.go 等文件构成，PHP 侧桥接代码位于 frankenphp.c、frankenphp.h，而 Caddy 模块注册与命令入口位于 caddy 目录，最终可执行文件入口为 caddy/frankenphp/main.go。
提示：Windows 用户请使用 WSL 来运行 FrankenPHP。
二、安装方式
FrankenPHP 提供多种安装途径，覆盖 Linux、macOS 与容器环境。下表汇总了各方式的适用场景：
| 安装方式 | 适用系统 | 扩展管理 |
|---|---|---|
| 安装脚本 | Linux/macOS（自动检测） | 不可额外安装扩展 |
| 静态二进制 | Linux/macOS（开发用途） | 不可额外安装扩展 |
| rpm 包 | 使用dnf的系统（Fedora/RHEL 系） | dnf或 PIE |
| deb 包 | 使用apt的系统（Debian/Ubuntu 系） | apt或 PIE |
| Docker | 任意支持 Docker 的系统 | 自定义镜像构建 |
| Homebrew | macOS/Linux | PIE |
1. 安装脚本
在终端执行以下命令，脚本会自动检测系统与架构，并安装匹配的版本：
curl https://frankenphp.dev/install.sh | sh仓库根目录的 install.sh 正是该脚本的实现：它会通过uname -s/uname -m判断操作系统与架构（Linux 的aarch64/x86_64），并优先检测dnf、apt-get等包管理器，将 FrankenPHP 安装为对应发行版的原生软件包；否则回退到直接下载预编译静态二进制到当前目录（可通过BIN_DIR环境变量指定安装目录）。
2. 静态二进制
官方为 Linux 与 macOS 提供面向开发用途的静态 FrankenPHP 二进制，内置 PHP 8.4 及主要 PHP 扩展：
- 下载地址：官方 Releases 页面。
- 扩展说明：常用扩展已内置在二进制中，无法再安装额外的 PHP 扩展（静态二进制场景下，PHP 扩展必须编译进二进制本体）。
3. rpm 包（dnf 系统）
面向所有使用dnf的系统，安装步骤如下：
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 安装：
sudo dnf install pie-zts sudo pie-zts install asgrim/example-pie-extension安装后，systemd 服务使用的 Caddyfile 位于/etc/frankenphp/Caddyfile，php.ini位于/etc/php-zts/php.ini（详见 install.sh 中的安装输出）。
4. deb 包（apt 系统）
面向所有使用apt的系统，先添加官方仓库再安装：
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-extension5. 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://localhost而非https://127.0.0.1，以便接受自签名证书。如需更换域名，请设置SERVER_NAME环境变量。
6. Homebrew
macOS 与 Linux 均可通过 Homebrew 安装：
brew install dunglas/frankenphp/frankenphp扩展安装：使用 PIE。
三、基础使用：两个核心命令
FrankenPHP 提供两条开箱即用的命令：php-server（生产可用的 PHP Web 服务器）与php-cli（CLI 脚本执行器）。
1. 提供静态与 PHP 文件服务：php-server
在当前目录提供内容服务：
frankenphp php-server该命令在 caddy/php-server.go 中注册，支持以下参数：
| 参数 | 简写 | 作用 |
|---|---|---|
--domain=<example.com> | -d | 指定域名；同时启用 HTTPS，并切换默认监听端口为 443 |
--root=<path> | -r | 站点根目录 |
--listen=<addr> | -l | 自定义监听地址 |
--worker=/path/to/worker.php[,nb-workers] | -w | 启用 Worker 模式，可多次指定 |
--watch[=<glob-pattern>] | — | 监听文件变化并重启 Worker，可重复指定 |
--access-log | -a | 开启访问日志 |
--debug | -v | 开启详细调试日志 |
--mercure | -m | 启用内置 Mercure.rocks hub |
--no-compress | — | 关闭 Zstandard、Brotli、Gzip 压缩 |
从源码实现可以看到其默认行为：
- 未指定
--listen时，若无域名则监听:80，有域名则监听 443（HTTPS）； - 未指定
--root且处于嵌入模式时回退到public/； - 自动构建路由：目录请求重定向（308）→ index 文件重写 →
*.php交给 FrankenPHP 处理 → 其余资源交给file_server； - 默认开启 zstd/br/gzip 压缩（除非
--no-compress）。
2. 执行命令行脚本：php-cli
frankenphp php-cli /path/to/your/script.php该命令在 caddy/php-cli.go 中注册，行为与 PHP CLI SAPI 类似：它会保留argv语义（第 0 个参数为程序自身），并将脚本执行交给 cli.go 中的ExecuteScriptCLI，最终返回脚本的退出状态码。
3. 作为系统服务运行
通过 deb/rpm 包安装后，可用 systemd 管理服务：
sudo systemctl start frankenphp仓库中的 package/debian/frankenphp.service 与 package/rhel/frankenphp.service 展示了服务配置要点：
- 启动前先执行
frankenphp validate --config /etc/frankenphp/Caddyfile校验配置； - 以
frankenphp专用用户运行，工作目录为/var/lib/frankenphp； - 通过
AmbientCapabilities=CAP_NET_BIND_SERVICE仅授予绑定 80/443 端口所需的最小权限； - 配置了
ProtectHome、ProtectSystem、PrivateTmp等加固选项； - 热重载：
sudo systemctl reload frankenphp（对应frankenphp reload --config ... --force）。
Alpine 的 OpenRC 初始化脚本 package/alpine/frankenphp.openrc 提供了等价的启停与重载逻辑。
四、快速上手示例
安装后，在任意包含 PHP 文件的目录启动服务：
frankenphp php-server打开http://localhost（若设置了域名则访问对应 HTTPS 地址）即可访问站点。仓库根目录的 testdata/index.php 与 package/content/index.php 可作为最简单的 PHP 入口文件参考。
若需要更精细的控制，可通过 Caddyfile 配置。仓库提供了两个现成模板：
- 简化版示例配置 caddy/frankenphp/Caddyfile：包含
php_server站点块、SERVER_NAME/SERVER_ROOT等环境变量占位、可选的 Mercure/Vulcain 模块（默认注释）、以及import Caddyfile.d/*.caddyfile扩展机制； - 发行版安装默认使用的 package/Caddyfile。
五、官方文档导航
日语版 README 提供了完整的文档索引，对应仓库 docs 目录中的同名文档：
| 主题 | 文档（仓库路径） |
|---|---|
| 经典模式（classic） | docs/classic.md |
| Worker 模式 | docs/worker.md |
| Early Hints（103 状态码） | docs/early-hints.md |
| 实时功能（Mercure） | docs/mercure.md |
| 大静态文件高效传输（X-Sendfile） | docs/x-sendfile.md |
| 配置（Caddyfile、php.ini、环境变量） | docs/config.md |
| Docker 镜像 | docs/docker.md |
| 生产环境部署 | docs/production.md |
| 性能优化 | docs/performance.md |
| 独立可执行 PHP 应用（embed） | docs/embed.md |
| 静态二进制构建 | docs/static.md |
| 从源码编译 | docs/compile.md |
| 监控（metrics） | docs/metrics.md |
| Laravel 集成 | docs/laravel.md |
| 已知问题 | docs/known-issues.md |
| 贡献与调试 | docs/CONTRIBUTING.md |
此外，日语版 README 还列出了社区提供的框架示例与骨架项目（Symfony、API Platform、Laravel、Sulu、WordPress、Drupal、Joomla、TYPO3、Magento2 等），可作为落地实践的参考起点。
六、进阶指引：从入门到源码
当你已经能成功启动 FrankenPHP 后，可按以下路径继续深入：
- 了解 Worker 模式：阅读 docs/worker.md 与 worker.go，理解应用常驻内存、跨请求复用的原理；
- 掌握完整配置：阅读 docs/config.md，掌握 Caddyfile 中
php_server/php指令、frankenphp全局块、php_ini、环境变量注入等全部配置手段； - 阅读 Caddy 模块源码：caddy/module.go 定义了 FrankenPHP 的 Caddy 模块（
php_server、php、worker 配置解析），caddy/caddy.go 负责模块注册与生命周期； - 探索 Go 库用法：若要把 PHP 嵌入自己的 Go 服务，可参考 frankenphp.go 的导出 API 与 README.md 中的 Go 库示例。
结语
FrankenPHP 把 Caddy 的自动 HTTPS、HTTP/2/3、Early Hints 与 PHP 应用运行时合二为一，提供了从一行命令（php-server/php-cli）到完整 Caddyfile 配置的渐进式使用路径。无论你是想在开发环境快速起一个 PHP 站点，还是在生产环境部署 Laravel/Symfony 并启用 Worker 模式，都可以从本文的安装与启动步骤出发，再按文档导航深入对应主题。
【免费下载链接】frankenphp🧟 The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
