FrankenPHP 源码编译实战指南以 libphp.so 动态库方式构建现代 PHP 应用服务器【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp导读本指南围绕 FrankenPHP 官方推荐的编译方式展开将 PHP 作为共享库shared library加载进 FrankenPHP 二进制从而构建出一个同时运行 PHP 与 Caddy 的应用服务器。你将掌握从安装 PHPHomebrew 或源码编译、配置libphp、安装可选系统依赖到使用xcaddy或直接go build生成最终二进制文件的完整流程并理解各编译标志背后的底层原理能够在此基础上自由扩展 Caddy 模块与 FrankenPHP 扩展。为什么采用PHP 作为共享库的编译方式在 FrankenPHP 中PHP 并非以独立进程运行而是被链接进 Caddy 所在的 Go 进程中。cgo.go中的#cgo指令清晰地揭示了这一设计Linux 与 macOS 上会链接-lphp即libphp动态库并附带-lm、-lutil、-ldl、-lresolv、-liconv等系统库依赖见 cgo.go。这份文档所介绍的正是这种加载动态 PHP 库的构建路径也是官方推荐的方法作为替代方案你也可以构建完全静态或基本静态的版本。采用这种方式有两大实际收益系统 PHP 复用直接使用 Homebrew 或源码安装的 PHP 版本无需为每个项目重复编译模块自由组合配合xcaddy可以像拼积木一样把额外的 Caddy 模块如 Mercure、Vulcain、Brotli 压缩等打进同一个二进制。安装 PHPFrankenPHP 与PHP 8.2 及以上版本兼容。方式一通过 HomebrewLinux 与 macOS在 Linux 和 macOS 上最便捷的途径是使用 Homebrew PHP 提供的 ZTS 预编译包。ZTSZend Thread Safety是 FrankenPHP 的硬性要求——因为多线程模型下每个 PHP worker 都运行在独立的线程中必须使用线程安全版本的 PHP。# 先安装 Homebrew若尚未安装 brew install shivammathur/php/php-zts brotli watcher brew link --overwrite --force shivammathur/php/php-ztsphp-zts线程安全版 PHP是 FrankenPHP 运行的基础brotli可选提供 Brotli 压缩支持watcher可选提供文件变更检测用于 worker 热重载。其中brew link --overwrite --force会强制将 ZTS 版 PHP 设为系统默认确保后续php-config指向的是正确的 ZTS 版本。方式二从源码编译 PHP如果你需要更精确地控制 PHP 编译参数可以自行编译。首先从 PHP 官方下载页 获取源码并解压tar xf php-* cd php-*/随后按平台运行configure脚本。以下标志是必需项但你完全可以在此基础上追加其他标志例如编译额外的扩展或特性。Linux 与 FreeBSD./configure \ --enable-embed \ --enable-zts \ --disable-zend-signals \ --enable-zend-max-execution-timers各标志的含义与底层关联标志作用--enable-embed生成可被宿主程序Go嵌入调用的libphp共享库这是PHP 作为共享库的基础--enable-zts启用线程安全与 FrankenPHP 的多线程 worker 模型严格对应--disable-zend-signals禁用 Zend 信号处理避免与 Go 运行时信号处理冲突--enable-zend-max-execution-timers启用 Zend 最大执行计时器配合 FrankenPHP 的请求超时控制macOS使用 Homebrew 安装必需与可选的构建依赖brew install libiconv bison brotli re2c pkg-config watcher echo export PATH/opt/homebrew/opt/bison/bin:$PATH ~/.zshrcbisonPHP 解析器生成所需macOS 自带版本过旧必须使用 Homebrew 版本并提前加入PATHre2c词法分析器生成器pkg-config用于解析libxml-2.0等依赖的编译参数cgo.go中#cgo darwin pkg-config: libxml-2.0正是依赖它libiconv、brotli、watcher分别为字符集转换、压缩与文件监听依赖。然后运行configure./configure \ --enable-embed \ --enable-zts \ --disable-zend-signals \ --with-iconv/opt/homebrew/opt/libiconv/注意 macOS 下需通过--with-iconv显式指向 Homebrew 的libiconv路径。编译并安装 PHPmake -j$(getconf _NPROCESSORS_ONLN) sudo make install$(getconf _NPROCESSORS_ONLN)会动态获取 CPU 核心数实现并行编译以加速构建。安装完成后系统即拥有libphp共享库和php-config工具后者是下一步编译 Go 应用时获取编译参数的关键。安装可选系统依赖部分 FrankenPHP 功能依赖可选的系统库。这些库必须预先安装如果你不需要对应功能也可以通过向 Go 编译器传递构建标签build tag将其禁用功能依赖库禁用的构建标签Brotli 压缩Brotlinobrotli文件变更时重启 worker热重载Watcher Cnowatcher这些构建标签在仓库源码中均有对应的构建约束build constraint。例如caddy/br.go以//go:build !nobrotli开头而caddy/br-skip.go则以//go:build nobrotli开头caddy/hotreload.go要求!nowatcher !nomercure一旦传入nowatcher或nomercure便会回退到 caddy/hotreload-skip.go 中的禁用实现。因此若你不需要热重载可传递-tagsnowatcher缩小二进制体积并省去 watcher 依赖若你不需要Brotli 压缩可传递-tagsnobrotli。编译 Go 应用PHP 就绪之后即可构建最终二进制。核心思路是通过环境变量CGO_CFLAGS和CGO_LDFLAGS把 PHP 的头文件路径、链接参数注入 Go 的 CGO 工具链从而把libphp链接进最终产物。推荐方式使用 xcaddyxcaddy是 Caddy 官方提供的构建工具也是编译 FrankenPHP 的推荐方式。它的额外优势在于可以在同一条命令中轻松追加自定义 Caddy 模块与 FrankenPHP 扩展CGO_ENABLED1 \ XCADDY_GO_BUILD_FLAGS-ldflags-w -s -tagsnobadger,nomysql,nopgx \ CGO_CFLAGS$(php-config --includes) \ CGO_LDFLAGS$(php-config --ldflags) $(php-config --libs) \ xcaddy build \ --output frankenphp \ --with github.com/php/frankenphp/caddy \ --with github.com/dunglas/mercure/caddy \ --with github.com/dunglas/vulcain/caddy # 在这里追加额外的 Caddy 模块与 FrankenPHP 扩展逐项拆解这条命令参数说明CGO_ENABLED1必须启用 CGO否则无法链接 C 语言的libphpCGO_CFLAGS$(php-config --includes)注入 PHP 头文件搜索路径供 CGO 编译 C 代码使用CGO_LDFLAGS$(php-config --ldflags) $(php-config --libs)注入 PHP 的链接参数与库列表最终把libphp链接进来XCADDY_GO_BUILD_FLAGS-ldflags-w -s ...-w -s去除 DWARF 调试信息与符号表以缩小二进制-tagsnobadger,nomysql,nopgx禁用 Caddy 中默认集成但未必需要的数据库存储模块--with github.com/php/frankenphp/caddy引入 FrankenPHP 的 Caddy 模块这是核心依赖--with github.com/dunglas/mercure/caddy引入 Mercure 实时消息推送模块--with github.com/dunglas/vulcain/caddy引入 Vulcain HTTP 模块关于模块导入路径的说明本仓库当前go.mod中的 module 路径为github.com/dunglas/frankenphpcaddy/frankenphp/main.go 中也使用github.com/dunglas/frankenphp/caddy、github.com/dunglas/mercure/caddy、github.com/dunglas/vulcain/caddy进行导入。文档中的github.com/php/frankenphp/caddy对应项目官方文档维护时的仓库迁移路径如果你希望严格以当前仓库源码为准可将--with参数替换为github.com/dunglas/frankenphp/caddy。两种写法指向同一套模块体系具体以你所使用的文档版本与仓库地址为准。此外xcaddy 还支持直接基于本地源码编译便于调试或打补丁--with github.com/dunglas/frankenphp$(pwd) \ --with github.com/dunglas/frankenphp/caddy$(pwd)/caddy已知问题musl libc 与 Symfony 的栈大小[!TIP]如果你使用musllibcAlpine Linux 的默认 libc且运行 Symfony可能需要增大默认栈大小。 否则可能遇到类似PHP Fatal error: Maximum call stack size of 83360 bytes reached during compilation. Try splitting expression的错误。解决办法是修改XCADDY_GO_BUILD_FLAGS环境变量例如XCADDY_GO_BUILD_FLAGS$-ldflags -w -s -extldflags \-Wl,-z,stack-size0x80000\根据你的应用需求调整栈大小数值。该问题源于musl默认线程栈较 Linux 主流的glibc更小Symfony 的表达式编译在深递归时容易触顶。通过-extldflags -Wl,-z,stack-size0x80000可以显式要求链接器把栈扩大到 512 KB0x80000。备选方式直接使用 go build不使用xcaddy同样可以编译只是你只能使用 FrankenPHP 官方默认内置的模块组合。步骤如下curl -L https://github.com/php/frankenphp/archive/refs/heads/main.tar.gz | tar xz cd frankenphp-main/caddy/frankenphp CGO_CFLAGS$(php-config --includes) CGO_LDFLAGS$(php-config --ldflags) $(php-config --libs) go build -tagsnobadger,nomysql,nopgx编译入口位于 caddy/frankenphp/main.go它导入 Caddy 标准模块集并通过空导入blank import挂载github.com/dunglas/frankenphp/caddy、github.com/dunglas/mercure/caddy与github.com/dunglas/vulcain/caddy三个模块最后调用caddycmd.Main()启动 Caddy。这解释了为什么无 xcaddy 路径依然默认带上了 Mercure 与 Vulcain——它们被硬编码进了官方入口文件。Brotli 压缩模块则由caddy/frankenphp/cbrotli.go//go:build !nobrotli以空导入方式引入github.com/dunglas/caddy-cbrotli这也再次印证了前文可选依赖与构建标签一节中nobrotli的作用。构建后的验证与运行编译产物frankenphp即为一个可直接执行的 Caddy 二进制。仓库根目录提供了开箱即用的 Caddyfile服务端配置与caddy/frankenphp/Caddyfile编译入口目录配套示例其中后者演示了典型配置{ frankenphp { {$FRANKENPHP_CONFIG} } } {$SERVER_NAME:localhost} { root {$SERVER_ROOT:public/} encode zstd br gzip php_server { #worker /path/to/your/worker.php } }要点解析php_serverFrankenPHP 的核心指令自动为 PHP 文件建立路由与 FastCGI 式处理可在此开启 worker 模式取消worker注释并指向你的 worker 脚本encode zstd br gzip启用 zstd、Brotli、gzip 三种压缩其中 Brotli 仅在编译时未传递nobrotli标签且系统安装了 Brotli 时可用{$SERVER_NAME:localhost}等环境变量占位符便于通过环境变量覆盖默认值无需修改配置文件。启动时直接运行./frankenphp run即可配合 docs/config.md 可深入了解全部配置指令。常见编译问题排查php-config: command not found说明 PHP 未安装或未加入PATH。确认已执行make install或在使用 Homebrew ZTS 时执行过brew link --overwrite --force。链接时报-lphp找不到确认 PHP 以--enable-embed编译生成了libphp共享库php-config --libs应输出包含-lphp的参数。热重载配置报错hot reload support disabled该错误来自 caddy/hotreload-skip.go意味着编译时传入了nowatcher或nomercure标签。若确实需要热重载应去掉对应标签并安装 watcher 依赖。Symfony 编译期栈溢出参考上文 musl 栈大小调整方案增大stack-size。默认模块组合与预期不符如果通过go build直接编译请确认入口文件 caddy/frankenphp/main.go 中的模块导入列表是否符合需求需要自定义模块时建议改用xcaddy。总结本文完整覆盖了 FrankenPHP 官方推荐的共享库编译路径先通过 Homebrew 或源码方式获得 ZTS 版 PHP 与libphp再按需安装 Brotli、Watcher 等可选依赖或使用构建标签禁用最后用xcaddy推荐或go build将 PHP 链接进 Caddy 二进制。理解CGO_CFLAGS/CGO_LDFLAGS与php-config的配合、掌握构建标签的开关语义以及知晓 musl 栈大小的坑将让你在任意 Linux/macOS 平台上稳定复现这一构建流程并为后续接入自定义 Caddy 模块与 FrankenPHP 扩展打下基础。【免费下载链接】frankenphp The modern PHP app server项目地址: https://gitcode.com/GitHub_Trending/fr/frankenphp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考