frankenphp 不解析或执行 composer.json 中的扩展声明，仅依赖底层 php 解释器已启用的扩展；ext-* 声明仅用于 composer 安装时校验，不触发安装，扩展可用性由 php 编译配置和 php.ini 决定。
FrankenPHP 本身不解析或执行 composer.json 中的 PHP 扩展声明（如 "ext-curl": "*"），它只运行 PHP 代码，而扩展是否可用，完全取决于底层 PHP 解释器的编译配置和 php.ini 加载情况。所谓“按 composer.json 自动决定装哪些扩展”，是个常见误解 —— Composer 不安装扩展，FrankenPHP 更不会替你装。
composer.json 的 ext-* 声明只做校验，不触发安装
你在 composer.json 里写 "ext-redis": "*" 或 "ext-mbstring": "*"，只是告诉 Composer：“我运行时必须有这个扩展”。Composer 在 install 或 update 阶段会检查当前 PHP 环境是否已启用对应扩展；如果没启用，就直接报错：
Root composer.json requires ext-redis * but it is not present.
这个检查发生在 FrankenPHP 启动前，但不会自动帮你启用或安装 redis.so。它只是个守门人，不是安装器。
- FrankenPHP 构建时用的 PHP 是静态链接还是动态加载扩展，由构建脚本（比如
Dockerfile或frankenphp build）决定 -
composer install --ignore-platform-reqs会跳过所有ext-*和php版本检查 —— 这在打包阶段常用，但掩盖了真实依赖风险 - 若你在本地开发环境启用了
ext-gd，但 CI 构建用的 FrankenPHP 镜像没编译 GD，composer install就会失败（除非加--ignore-platform-reqs）
FrankenPHP 打包时如何确保扩展可用
FrankenPHP 的“打包为可执行文件”流程中，扩展支持靠的是底层 PHP 构建环节，不是 composer.json。你需要显式控制 PHP 编译参数或选用预编译镜像：
- 使用官方 FrankenPHP Docker 镜像时，查清其标签说明（如
frankenphp:1.2-php8.3-apache）是否包含你需要的扩展；常见扩展（curl,mbstring,json,xml）通常默认开启，但redis,pdo_pgsql,gd等需额外确认 - 自定义构建时，在
Dockerfile中通过docker-php-ext-install或pecl install显式启用：例如docker-php-ext-install redis mbstring - 若用
frankenphp buildCLI 工具生成二进制，它底层调用的是go build+ PHP embed，此时 PHP 必须是已编译好扩展的版本 —— 不能指望 FrankenPHP 在 build 时去apt install php-redis
运行时检测比 composer.json 声明更可靠
有些扩展（比如 ext-gd）只在特定功能路径中用到，硬性要求它出现在 composer.json 会导致部署失败，但实际又未必需要。这时应放弃平台声明，改用运行时探测：
if (!extension_loaded('gd')) {
throw new RuntimeException('GD extension required for image processing');
}
或者更轻量地用 function_exists() 或 class_exists()：
if (!class_exists('GdImage')) {
// fallback to imagick or return error
}
- 这种判断放在业务逻辑入口或服务提供者里，比让
composer install卡住更灵活 - FrankenPHP 的热重载或 worker 模式下，这类检查还能避免启动后首次请求才暴露缺失问题
- 注意：不要在
autoload.php或config/加载阶段做扩展检测，可能破坏自动加载顺序
真正容易被忽略的点是：FrankenPHP 的 PHP 环境和你本地 php -v 输出的不是一回事。打包前务必用相同基础镜像或构建环境跑一次 composer install，别依赖本地验证结果。扩展是否就位，得看最终二进制里嵌入的 PHP 是怎么编译出来的，而不是看你的 composer.json 写了什么。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
