构建PHP8 Laravel Docker镜像时docker-php-ext-install执行报错

问题根因 #

• PHP 7.4及以上版本中，mbstring扩展的正则匹配逻辑依赖独立的oniguruma库，Alpine环境下需要手动安装oniguruma-dev依赖包。你当前的依赖列表中缺失该包，会直接导致mbstring编译失败，中断整个扩展安装流程，这也是切换到7.4、8.0版本镜像后构建失败的核心原因。
• 你使用的gd扩展配置参数是PHP 7.3及更早版本的旧语法，PHP 7.4+版本已经废弃--with-gd、--with-freetype-dir、--with-jpeg-dir、--with-png-dir这类参数，即便修复前序依赖问题，执行到gd配置步骤时依然会报错。

修复步骤 #

1. 在apk安装依赖的列表中补充oniguruma-dev包，修改后的依赖安装命令如下：

RUN apk update && apk add \
    build-base \
    freetype-dev \
    libjpeg-turbo-dev \
    libpng-dev \
    libzip-dev \
    oniguruma-dev \
    zip \
    jpegoptim optipng pngquant gifsicle \
    vim \
    unzip \
    git \
    curl

2. 替换gd扩展的配置参数为PHP 8兼容写法，不需要手动指定依赖头文件目录，官方镜像会自动检索对应路径，同时可以将gd扩展和其他扩展合并安装减少镜像层数：

RUN docker-php-ext-install pdo_mysql mbstring zip exif pcntl
RUN docker-php-ext-configure gd --with-freetype --with-jpeg
RUN docker-php-ext-install gd

排查建议 #

• 如果构建时无法定位具体报错的扩展，可以在docker-php-ext-install命令前添加set -x打印详细执行日志，或者拆分命令逐个安装扩展，就能快速定位失败点。
• 跨大版本升级PHP（比如7.3升级到8.0）时，不要直接照搬旧版本Dockerfile配置，部分扩展的编译参数、依赖要求会有变更，需要对应版本的规则调整。

内容的提问来源于stack exchange，提问作者pong pon