FrankenPHP 容器镜像构建自定义 PHP 扩展教程-php教程-PHP中文网

frankenphp 官方镜像不支持直接用 pecl install 或 phpize 编译 c 扩展，因其为极简镜像，缺失 php-config、php-dev 头文件及 gcc/make/autoconf 等构建工具；必须通过多阶段构建，使用 static-builder-musl/glibc 镜像显式编译 .so 文件，并严格匹配 php 版本与 abi。

frankenphp 容器镜像构建自定义 php 扩展教程

FrankenPHP 容器里不能直接用 pecl install 或 phpize 编译传统 C 扩展——因为官方镜像（如 dunglas/frankenphp:static）是 scratch 或 alpine 极简基础镜像，不含构建工具链，也**不挂载 PHP 源码和头文件**。想加扩展，必须走多阶段构建 + 显式编译流程。

为什么 `docker-php-ext-install` 在 FrankenPHP 镜像里会失败

常见报错类似：configure: error: Cannot find php-config 或 fatal error: Zend/zend.h: No such file or directory。根本原因有三个：

官方 static 镜像不含 php-config、phpize 和 php-dev 头文件包
frankenphp 进程本身不依赖系统 PHP 安装，它自带嵌入式 PHP 运行时，但不暴露 SDK 接口给容器内常规构建命令
即使你用 alpine 版本镜像，它默认也没装 gcc、make、autoconf 等编译依赖

正确做法：用 builder 阶段显式编译扩展 .so 文件

必须借助 FrankenPHP 提供的 static-builder-musl（或 static-builder-glibc）镜像，它预装了完整构建环境、PHP 源码和头文件。关键步骤如下：

第一阶段用 FROM dunglas/frankenphp:static-builder-musl AS builder
在 builder 阶段执行 COPY 扩展源码（如 ext/myext/），再运行 docker-php-ext-configure + docker-php-ext-install
确认生成的 .so 文件路径，通常是 /usr/local/lib/php/extensions/no-debug-non-zts-20220829/myext.so（版本号随 PHP 8.2+ 变动）
第二阶段用 FROM scratch 或 FROM dunglas/frankenphp:static，只 COPY --from=builder 扩展文件和 php.ini 配置片段

示例关键片段：

btpanel phpsite 宝塔面板PHP网站

宝塔面板 PHP 网站管理：站点创建、删除、启停、PHP 版本切换、域名管理、SSL证书管理、伪静态管理、数据库管理

下载

FROM dunglas/frankenphp:static-builder-musl AS builder
COPY ext/myext /tmp/myext
RUN cd /tmp/myext && phpize && ./configure && make && make install

FROM dunglas/frankenphp:static
COPY --from=builder /usr/local/lib/php/extensions/*/myext.so /usr/local/lib/php/extensions/
COPY myext.ini /usr/local/etc/php/conf.d/

Go 编写的 FrankenPHP 扩展不需要编译 .so

如果你的扩展是用 Go 写的（比如通过 frankenphp.RegisterExtension() 注册），它**不生成 .so 文件，也不走 PHP 的传统扩展加载机制**。它是被直接链接进 frankenphp 二进制里的：

你只需把 Go 扩展代码 import 进主程序，调用 frankenphp.RegisterExtension(...)
然后用 go build -o frankenphp ./cmd 重新构建整个 FrankenPHP 可执行文件
最终镜像里替换掉原始 /usr/local/bin/frankenphp 即可，无需额外 .so 或 php.ini 条目
这种模式下，扩展函数在 PHP 中直接可用，且能安全使用 goroutine —— 但代价是每次改扩展都要重编译整个服务器

容易忽略的兼容性陷阱

FrankenPHP 的扩展加载与传统 PHP-FPM 有本质区别，以下三点常被跳过导致运行时报错：

php.ini 中启用扩展必须用 extension=myext.so，不能写成 zend_extension=...（那是 Zend OPcache 或 Xdebug 用的）
扩展名后缀必须匹配目标架构：musl 镜像只能用 musl 编译的 .so，glibc 镜像同理；混用会报 invalid ELF header
PHP 版本 ABI 兼容性极敏感：FrankenPHP 8.2 镜像只能加载为 PHP 8.2 编译的扩展，哪怕只是小版本升级（8.2.1 → 8.2.3）也可能因内部结构微调而崩溃

最稳妥的做法，是始终用与生产镜像完全一致的 builder 镜像来编译扩展，且不跨大版本复用已编译的 .so 文件。