FrankenPHP官方镜像内置docker-php-extension-installer，可直接用install-php-extensions命令安装扩展（如opcache、pdo_mysql等），无需手动编译；若报“command not found”，说明未使用dunglas/frankenphp官方镜像。
直接用 install-php-extensions 命令安装
FrankenPHP 官方镜像（dunglas/frankenphp）内置了 docker-php-extension-installer 工具，不需要手动编译或配置 phpize。只要容器能联网，进容器执行一条命令就能装好扩展。
常见错误现象：执行 install-php-extensions 报 “command not found”——说明你用的不是官方镜像，而是自己从 scratch 或 Alpine 手动构建的精简版；或者用了 :static-builder 这类只含二进制的构建镜像，它不带这个工具。
- 进入运行中的容器：
docker exec -it your-frankenphp-container bash - 安装常用扩展：
install-php-extensions opcache pdo_mysql mbstring curl openssl zip - 安装完成后建议重启容器，避免扩展加载状态不一致
多阶段构建中静态安装扩展
如果你用的是生产级多阶段构建（比如基于 static-builder-musl），install-php-extensions 不可用，必须在构建阶段显式调用 docker-php-ext-install。
性能影响：静态构建时启用 opcache 和 pdo_mysql 是刚需，但像 gd 或 imagick 这类大体积扩展会显著增大最终镜像体积，musl 环境下还可能因缺少系统库而编译失败。
立即学习“PHP免费学习笔记（深入）”；
- 确保构建阶段基础镜像包含 dev 工具：
FROM dunglas/frankenphp:static-builder-musl - 复制源码后执行：
RUN docker-php-ext-install opcache pdo_mysql mbstring - 注意：不能用
pecl install，因为static-builder镜像默认没装 pear / pecl
自定义 Dockerfile 中启用扩展但不重启容器
有些扩展（如 opcache）依赖 php.ini 配置生效，光装上还不够。FrankenPHP 默认加载 $PHP_INI_DIR/php.ini，但镜像里初始是 php.ini-production，得先激活。
容易踩的坑：直接 COPY php.ini /usr/local/etc/php/ 可能被后续层覆盖；用 RUN mv 更稳妥，但要注意时机——必须在 COPY . /app/public 之前，否则 $PHP_INI_DIR 可能未初始化。
- 推荐写法：
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini" - 再追加配置：
RUN echo "opcache.enable=1" >> "$PHP_INI_DIR/php.ini" - 验证是否生效：
docker run --rm your-image php -m | grep opcache
worker 模式下扩展行为差异
FrankenPHP 的 worker 模式让 PHP 进程常驻内存，这意味着扩展一旦加载就不会重载。所以像 opcache.revalidate_freq=0 这种开发期配置，在 worker 下会导致代码修改不生效——不是扩展没装，而是 OPcache 缓存没刷新。
关键点：worker 模式本身不改变扩展安装方式，但会放大配置错误的影响。ThinkPHP、Laravel 等框架在 worker 下对 mbstring、json、ctype 的依赖是刚性的，缺一个就卡在 frankenphp_handle_request() 前。
- 务必检查
php -m输出是否包含所有必需模块 - runtime 日志里出现
Call to undefined function mb_strlen()就是扩展缺失的典型信号 - 不要依赖 Caddy 的 error log 查扩展问题，它不记录 PHP 模块加载失败细节
最麻烦的不是装不上，而是装上了但没生效——尤其在 static-builder 构建流程里，RUN 指令顺序、环境变量作用域、ini 文件加载路径这三者稍有错位，扩展就等于白装。
