frankenphp 的 build 命令不支持 --php-extensions 参数,所有扩展必须静态编译进二进制;需通过官方 static-builder 镜像或 fork 仓库修改 build-static.sh 中的 extensions 列表来指定,且依赖关系和 c 库须完整。

frankenphp build 时 --php-extensions 参数不生效?
FrankenPHP 的 frankenphp build 命令**根本不支持 --php-extensions 这类参数**——它不会动态加载或编译扩展。所有 PHP 扩展必须在构建前就「静态链接进二进制」,而官方 CLI 工具默认只包含内置扩展(curl、json、opcache、pdo_sqlite 等)。你看到的 extension=yac.so 或 extension=swoole.so 这类配置,在独立二进制中完全被忽略。
第三方扩展怎么进独立二进制?只有两种可行路径
想让 yac、redis、grpc 等扩展可用,必须提前把它们编译进 FrankenPHP 自身的二进制里,而不是靠 php.ini 启用:
- 使用
dunglas/frankenphp:static-builder镜像 +build-static.sh脚本:这是官方推荐方式,通过环境变量PHP_EXTENSIONS=ctype,iconv,pdo_mysql,redis指定要编译的扩展名(注意是扩展名,不是 .so 文件名) - 自己 fork FrankenPHP 仓库,修改
build-static.sh中的EXTENSIONS列表,再用 Go 构建整个项目:适合需要定制内核或启用非常规扩展(如zts版本)的场景 - 别指望用
pecl install或复制.so文件到某个目录——独立二进制运行时不读取系统 ext/ 目录,也不支持dlopen()
扩展名写错、顺序不对、依赖缺失的典型表现
即使你在 build-static.sh 里写了 PHP_EXTENSIONS=redis,grpc,构建也可能静默失败或运行时报错:
-
redis依赖sockets和json,但sockets不在默认启用列表里 → 构建成功但运行时class Redis not found - 写了
grpc却没加protobuf→PHP Fatal error: Uncaught Error: Call to undefined function grpc_init() - 扩展名大小写错误,比如写成
Redis或REDIS→ 构建脚本跳过该扩展,无提示 - 某些扩展(如
yaml)需额外 C 依赖(libyaml),Docker 构建镜像里没预装 → 构建中途报configure: error: not found libyaml
验证扩展是否真进了二进制?别信 php.ini,要看运行时
生成的 myapp 二进制文件启动后,它内部的 PHP 解释器是否真加载了你要的扩展,唯一可信方式是让它自己说:
- 启动应用后访问
/info.php(内容为<?php print_r(get_loaded_extensions()); ?>),看返回数组里有没有你的扩展名 - 不要执行系统里的
php -m——那查的是宿主机 PHP,和你的二进制无关 - 如果用了自定义构建镜像,检查构建日志末尾是否有
Building extension: redis类似行;没有就说明没编进去 - 注意:
get_loaded_extensions()返回的是字符串数组,不含.so后缀,所以查"redis",不是"redis.so"
最常被忽略的一点:FrankenPHP 独立二进制的扩展能力,本质是「编译时决策」,不是「运行时配置」。写错一行 PHP_EXTENSIONS 环境变量,就得重跑整个 Docker 构建流程——没有热更新,也没有 fallback 机制。
php免费学习视频:立即使用
踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!











