最省事方式是使用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</container-name>
• 安装扩展（例如 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 自定义构建：

• 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）和依赖名不同，别抄错。

btpanel phpsite 宝塔面板PHP网站

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

下载

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></ext> 交叉验证。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！