最省事方式是使用FrankenPHP官方镜像dunglas/frankenphp内置的install-php-extensions脚本，进入容器执行install-php-extensions opcache redis igbinary即可安装扩展，但需重启进程生效；非官方或旧版镜像可能缺失该脚本。
直接用 install-php-extensions 脚本最省事
FrankenPHP 官方镜像 dunglas/frankenphp 已预装 install-php-extensions，进容器就能用，不用改 Dockerfile、不需编译环境。这是最推荐的日常调试和轻量生产追加方式。
常见错误现象：command not found: install-php-extensions —— 多半是因为用了非官方基础镜像（比如自己基于 php:8.3-cli 从头构建），或镜像版本太旧（v1.1.0 之前部分镜像未内置）。
- 进入容器：
docker exec -it <container-name> sh - 安装扩展（例如
opcache、redis、igbinary）：install-php-extensions opcache redis igbinary - 安装完必须重启 PHP 进程（FrankenPHP 不支持热加载扩展）：
kill 1或supervisorctl restart frankenphp（取决于启动方式） - 验证是否生效：
php -m | grep redis或访问/phpinfo.php
需要自定义编译参数时必须重写 Dockerfile
当你要装的扩展依赖外部库（比如 gd 需要 libjpeg、pdo_pgsql 需要 libpq-dev），或者想控制 PHP 构建选项（如启用 ZTS、禁用 debug），install-php-extensions 就不够用了——它只处理「开箱即用」的扩展。
此时你得基于 dunglas/frankenphp 自定义构建：
立即学习“PHP免费学习笔记（深入）”；
- FROM dunglas/frankenphp:latest
- RUN apk add --no-cache libjpeg-turbo-dev libpng-dev freetype-dev postgresql-dev
- RUN docker-php-ext-configure gd --with-jpeg-dir=/usr/include/libjpeg-turbo --with-freetype-dir=/usr/include/freetype2
- RUN docker-php-ext-install gd pdo_pgsql
- RUN rm -rf /tmp/* /var/cache/apk/*
注意：docker-php-ext-install 是 PHP 官方镜像提供的脚本，FrankenPHP 镜像兼容它；但 Alpine 和 Debian 系基础镜像的包管理命令（apk vs apt-get）和依赖名不同，别抄错。
Go 扩展不能用传统方式安装
FrankenPHP 的 Go 扩展（比如用 frankenphp extension-init 生成的）不是 .so 文件，也不走 extension= 加载流程。它必须在 Go 主程序里显式注册，然后随 FrankenPHP 一起编译进二进制。
所以你不能在运行中的 FrankenPHP 容器里「追加」一个 Go 扩展——它本质上是一个独立的 Go 应用，只是嵌入了 PHP 引擎。
- 要添加 Go 扩展：写好
main.go+ 扩展函数，用go build重新编译整个服务 - 不能靠
php.ini或install-php-extensions注册 - 调试阶段可配合
frankenphp.Run()启动开发服务器，但上线仍需静态编译
扩展冲突和 php.ini 生效顺序容易被忽略
FrankenPHP 容器启动时会按固定顺序加载配置：先读 /etc/php/conf.d/*.ini，再读 $PHP_INI_DIR/php.ini。如果你通过 install-php-extensions 安装扩展，它默认在 /etc/php/conf.d/ 下写 docker-php-ext-*.ini；但如果你手动挂载了自定义 php.ini，且里面写了 extension=opcache，而系统又已加载过 opcache.ini，就可能触发重复加载报错：PHP Warning: Module 'opcache' already loaded。
解决办法很直接：
- 检查加载顺序：
php --ini看配置文件路径和加载顺序 - 删掉重复项：
rm /etc/php/conf.d/docker-php-ext-opcache.ini（如果确定已在主php.ini中启用） - 避免挂载整个
php.ini，改用echo "opcache.enable=1" > /etc/php/conf.d/my-opcache.ini增量覆盖
真正麻烦的从来不是装不上，而是装上了却因配置叠加、路径错位、扩展依赖链断裂，导致 PHP 启动失败或函数不可见——这些细节在 docker logs 里往往只有一行 warning，得盯着 php -m 和 php --ri <ext> 交叉验证。
