FrankenPHP的PHP_EXTENSIONS变量支持传哪些扩展名-php教程-PHP中文网

frankenphp的php_extensions变量仅支持预编译白名单中的扩展，当前稳定支持ctype、curl、iconv、json、mbstring、openssl、pdo、pdo_sqlite、phar、posix、session、sqlite3、tokenizer、xml、zip；pdo_mysql、redis等依赖外部库的扩展不在白名单中，强行使用会导致构建失败。

frankenphp的php_extensions变量支持传哪些扩展名

PHP_EXTENSIONS 变量只接受用英文逗号分隔的、已知且预编译支持的扩展名字符串，不是所有 PHP 扩展都能传——它本质是 FrankenPHP 静态构建脚本（build-static.sh）中硬编码白名单的映射键。

哪些扩展名能用：看 FrankenPHP 官方预编译支持列表

FrankenPHP 的 build-static.sh 脚本在编译阶段会根据 PHP_EXTENSIONS 值启用对应 C 源码模块，并链接进最终二进制。目前（2026 年 10 月）稳定支持的扩展名包括：

ctype
curl
iconv
json
mbstring
openssl
pdo（仅作为 PDO 抽象层，不带驱动）
pdo_sqlite（SQLite 驱动，最常用）
phar
posix
session
sqlite3
tokenizer
xml
zip

注意：pdo_mysql、redis、memcached 等需外部库依赖的扩展**不在默认白名单中**，强行传入会导致构建失败（报错类似 extension 'pdo_mysql' not found in PHP_EXTENSIONS list）。

为什么有些常见扩展不能直接用

FrankenPHP 静态打包的目标是「最小可行生产二进制」，所以只集成零依赖或系统级依赖极简的扩展：

btpanel phpsite 宝塔面板PHP网站

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

下载

pdo_mysql 依赖 libmysqlclient 或 mysqlnd，静态链接风险高、体积大，官方未启用
redis 依赖 hiredis，且需运行时动态加载 .so，与静态二进制模型冲突
gd 依赖 libpng/libjpeg/libfreetype，跨平台构建稳定性差，暂未纳入
任何需要 dl() 或 INI 中 extension=xxx.so 动态加载的扩展，都不适用于 PHP_EXTENSIONS 流程

如何确认某个扩展是否可用

最可靠的方式是查源码中的白名单定义——在 FrankenPHP 仓库的 build-static.sh 文件里搜索 case "$ext" in，你会看到类似这样的片段：

case "$ext" in
  ctype|curl|iconv|json|mbstring|openssl|pdo|pdo_sqlite|phar|posix|session|sqlite3|tokenizer|xml|zip)
    PHP_CONFIGURE_ARGS+=("--enable-$ext")
    ;;
  *)
    echo "extension '$ext' not found in PHP_EXTENSIONS list" >&2
    exit 1
    ;;
esac

如果你确实需要 pdo_mysql 这类扩展，唯一可行路径是：放弃静态二进制，改用 dunglas/frankenphp:alpine 这类常规镜像，在容器内用 apk add php81-pdo-mysql 安装，再挂载应用代码运行。

别指望靠改环境变量绕过白名单——PHP_EXTENSIONS=redis,grpc 不会 magically 生效，构建脚本会直接退出。