FrankenPHP 官方镜像不支持直接用 pecl install 或 phpize 编译 C 扩展，因其为极简镜像，缺失 php-config、php-dev 头文件及 gcc/make/autoconf 等构建工具；必须通过多阶段构建，使用 static-builder-musl/glibc 镜像显式编译 .so 文件，并严格匹配 PHP 版本与 ABI。
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配置片段
示例关键片段：
立即学习“PHP免费学习笔记（深入）”；
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 文件。
