frankenphp 官方镜像不支持运行时安装扩展，必须通过自定义构建集成：基于 dunglas/frankenphp:1.2（debian）镜像，先装系统依赖、下载 php 源码至 /usr/src/php，再用 docker-php-ext-install 安装 pdo_mysql、gd 等扩展。
FrankenPHP 是基于 PHP 的现代 Web 服务器，由 Symfony 团队维护，底层复用 PHP 的 SAPI（如 embed 或 cli），并深度集成 HTTP/3、QUIC 和 Server-Sent Events。它不是基于传统 PHP-FPM 或 Apache 的镜像，因此不能直接套用 php:8.2-fpm-alpine 那套 docker-php-ext-install 流程。
关键点在于：*FrankenPHP 官方 Docker 镜像（docker.io/dunglas/frankenphp）默认不包含 `docker-php-ext-脚本**，也不带/usr/src/php源码或phpize` 环境——它是一个精简、生产就绪的运行时镜像，不支持在运行中动态编译安装扩展。
所以，“追加 PHP 扩展”的唯一可靠方式是：构建自定义 FrankenPHP 镜像，在构建阶段集成所需扩展。
✅ 正确做法：基于 FrankenPHP 基础镜像构建含扩展的镜像
FrankenPHP 官方推荐使用 Debian 或 Alpine 多阶段构建，利用其提供的 frankenphp-build 工具链（实际是封装了 PHP 编译流程）。但更常用、更可控的方式是：复用 FrankenPHP 的基础层 + 手动补全 PHP 构建依赖 + 安装扩展。
1. 确认 FrankenPHP 镜像类型与 PHP 版本
先查清你用的是哪个变体：
-
dunglas/frankenphp:1.2→ 基于 Debian（bookworm），PHP 8.3 -
dunglas/frankenphp:1.2-alpine→ 基于 Alpine 3.20，PHP 8.3
⚠️ 注意：Alpine 版本*不带 `docker-php-ext-
脚本**，且 musl libc 兼容性有限（如某些扩展如sqlsrv、pdo_sqlsrv` 不支持）；推荐优先选 Debian 版。
2. 在 Dockerfile 中添加扩展（以 pdo_mysql 和 gd 为例）
FROM dunglas/frankenphp:1.2
# 设置非交互模式（Debian）
ENV DEBIAN_FRONTEND=noninteractive
# 安装系统依赖（关键！缺依赖会导致 docker-php-ext-install 卡住或失败）
RUN apt-get update && apt-get install -y --no-install-recommends \
libpng-dev \
libjpeg-dev \
libfreetype-dev \
libwebp-dev \
libzip-dev \
libpq-dev \
zlib1g-dev \
&& rm -rf /var/lib/apt/lists/*
# 启用 PHP 源码（FrankenPHP 镜像默认不含 /usr/src/php，需手动提取）
RUN php -r "copy('https://www.php.net/distributions/php-8.3.14.tar.xz', '/tmp/php.tar.xz');" \
&& cd /usr/src \
&& tar -xf /tmp/php.tar.xz \
&& mv php-8.3.14 php \
&& rm /tmp/php.tar.xz
# 安装扩展（FrankenPHP 镜像自带 docker-php-ext-* 脚本，但需源码存在才能用）
RUN docker-php-ext-configure gd \
--with-jpeg \
--with-webp \
--with-freetype \
&& docker-php-ext-install -j$(nproc) \
pdo_mysql \
gd \
zip \
opcache
# 清理构建缓存（可选，减小体积）
RUN apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /usr/src/php
✅ 提示：FrankenPHP 1.2+ 镜像已预置
docker-php-ext-install等脚本（位于/usr/local/bin/），只要补上/usr/src/php源码即可调用。
3. 验证扩展是否生效
在容器启动后执行：
docker exec -it your-frankenphp-container php -m | grep -E "(pdo_mysql|gd|zip)" # 或访问 /health?format=json 查看 FrankenPHP 内置健康检查（含 loaded extensions 列表）
也可放一个 info.php：
<?php phpinfo();
然后通过浏览器打开确认扩展模块是否列出。
❌ 不推荐/不可行的方式
docker exec -it container bash && docker-php-ext-install xxx
→ 失败：缺少/usr/src/php、phpize、系统 dev 包，且修改不会持久化。直接
pecl install
→ 失败：无phpize、无gcc、无make（FrankenPHP 镜像默认不含编译工具链）。挂载
.so文件 + 手动写php.ini
→ 高风险：扩展 ABI 不匹配（PHP 版本、ZTS、架构）、加载失败或崩溃。
? 补充：快速启用常见扩展的简化写法（Debian 版）
如果你只加 opcache 和 pdo_mysql（无图形依赖），可跳过 gd 相关 configure：
FROM dunglas/frankenphp:1.2 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y --no-install-recommends libpq-dev && rm -rf /var/lib/apt/lists/* RUN docker-php-ext-install pdo_mysql opcache
FrankenPHP 追加扩展的本质，是把它当作一个「轻量 PHP 运行时」来定制，而不是“开箱即用的 FPM 替代品”。构建一次、复用长久，既安全又可控。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
