PHP扩展Docker安装失败主因是系统依赖缺失、启用未显式执行或volumes覆盖配置；需装全libssl-dev等开发库，用docker-php-ext-enable启用扩展，并避免挂载整个conf.d目录。
PHP扩展在Docker中安装失败，多数不是PHP本身问题，而是构建环境缺失依赖、配置顺序错误或路径被覆盖所致。核心在于：系统库要装全、扩展启用要显式、挂载配置要谨慎。
检查基础依赖是否完整
PHP扩展编译阶段高度依赖系统级开发库，缺一个就可能卡住或静默失败：
- Debian/Ubuntu镜像：必须安装 libssl-dev、libxml2-dev、libzip-dev、libjpeg-dev、libpng-dev、libfreetype6-dev 等（例如 zip 扩展必靠 libzip-dev，gd 必靠图像库）
- Alpine镜像：对应安装 openssl-dev、libxml2-dev、libzip-dev、jpeg-dev、png-dev、freetype-dev；注意 Alpine 的包名前缀常为
libjpeg-turbo-dev而非libjpeg-dev - 运行
apk list | grep -i openssl（Alpine）或apt list --installed | grep ssl（Debian）确认已安装，而非仅存在运行时库
确保扩展正确启用而非仅“安装”
docker-php-ext-install 只负责编译并复制 .so 文件，不会自动写入 php.ini 启用它：
- 执行
RUN docker-php-ext-enable openssl（或其他扩展名），这是官方推荐方式，会自动生成/usr/local/etc/php/conf.d/docker-php-ext-openssl.ini - 若手动编辑 php.ini，请确认 extension=openssl（不带 .so），且该文件位于
conf.d/目录下，PHP 启动时能扫描到 - 验证是否生效：进容器运行
php -m | grep openssl或php -r "echo extension_loaded('openssl') ? 'yes' : 'no';"
警惕 volumes 挂载导致的配置覆盖
开发中常用 volumes 挂载自定义 php.ini 或整个 conf.d 目录，极易覆盖 Docker 镜像预置的扩展加载配置：
立即学习“PHP免费学习笔记（深入）”；
- 避免挂载
/usr/local/etc/php/conf.d/整个目录；如需自定义，只挂载单个配置文件（如./php-custom.ini:/usr/local/etc/php/conf.d/custom.ini） - 若已挂载并发现 openssl 消失，先检查容器内
ls /usr/local/etc/php/conf.d/是否只剩你挂载的文件，原生的docker-php-ext-openssl.ini已被清空 - 日志中出现
Module 'openssl' already loaded，说明有重复加载（比如手动加了一次，又通过 docker-php-ext-enable 加了一次）
Alpine 与 Debian 镜像的关键差异处理
同一份 Dockerfile 在不同基础镜像上可能表现迥异，需针对性调整：
- Alpine 上 PECL 安装扩展前，必须先装
php*-pear php*-dev（版本号需严格匹配，如 php82-pear、php82-dev）；php7-pear在 PHP 8.2 镜像中会报错 - Alpine 缺少 g++、make 等工具链？补上
build-base autoconf automake autoconf（Alpine 的 meta 包） - Debian 镜像中，务必在 RUN 命令开头统一设置
DEBIAN_FRONTEND=noninteractive，防止 apt 安装中途等待用户输入卡死
