Dockerfile构建PHP 8.1-fpm-alpine镜像时扩展安装失败求助

基于php:8.1-fpm-alpine构建镜像时，执行docker-php-ext-install报错，提示/usr/src/php/ext/libzip does not exist，类似错误也出现在freetype、libfreetype6-dev等包上。构建失败的错误日志如下：

#0 6.705 (25/26) Installing make (4.3-r0)
#0 6.726 (26/26) Installing re2c (2.1.1-r0)
#0 6.764 Executing busybox-1.34.1-r5.trigger
#0 6.770 OK: 255 MiB in 59 packages
#0 8.461 error: /usr/src/php/ext/libzip does not exist
#0 8.461 
#0 8.461 usage: /usr/local/bin/docker-php-ext-install [-jN] [--ini-name file.ini] ext-name [ext-name ...]
#0 8.461    ie: /usr/local/bin/docker-php-ext-install gd mysqli
#0 8.461        /usr/local/bin/docker-php-ext-install pdo pdo_mysql
#0 8.461        /usr/local/bin/docker-php-ext-install -j5 gd mbstring mysqli pdo pdo_mysql shmop
#0 8.461 
#0 8.461 if custom ./configure arguments are necessary, see docker-php-ext-configure
#0 8.461 
#0 8.461 Possible values for ext-name:
#0 8.496 bcmath bz2 calendar ctype curl dba dom enchant exif ffi fileinfo filter ftp gd gettext gmp hash iconv imap intl json ldap mbstring mysqli oci8 odbc opcache pcntl pdo pdo_dblib pdo_firebird pdo_mysql pdo_oci pdo_odbc pdo_pgsql pdo_sqlite pgsql phar posix pspell readline reflection session shmop simplexml snmp soap sockets sodium spl standard sysvmsg sysvsem sysvshm tidy tokenizer xml xmlreader xmlwriter xsl zend_test zip
#0 8.496 
#0 8.496 Some of the above modules are already compiled into PHP; please check
#0 8.496 the output of "php -i" to see which modules are already loaded.
------
failed to solve: executor failed running [/bin/sh -c apk update && apk add --no-cache --update linux-headers ${PHPIZE_DEPS}     && docker-php-ext-install     exif     mysqli     pdo     pdo_mysql     libzip     freetype    libfreetype6-dev     libjpeg62-turbo-dev     libpng-dev     && docker-php-ext-configure gd --with-freetype --with-jpeg     && docker-php-ext-install -j$(nproc) gd     && docker-php-ext-install opcache]: exit code: 1

原Dockerfile内容：

FROM php:8.1-fpm-alpine

# Install native PHP extensions
RUN apk update && apk add --no-cache --update linux-headers ${PHPIZE_DEPS} \
    && docker-php-ext-install \
    exif \
    mysqli \
    pdo \
    pdo_mysql \
    libzip \
    freetype\
    libfreetype6-dev \
    libjpeg62-turbo-dev \
    libpng-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd \
    && docker-php-ext-install opcache

错误根源 #

docker-php-ext-install只能用于安装PHP官方提供的内置扩展（错误日志里已列出所有可用扩展名），而你把libzip、freetype这类Alpine系统依赖包当成PHP扩展传给了这个命令，导致找不到对应扩展目录报错。此外：

• Alpine系统里没有libfreetype6-dev包，对应的包名是freetype-dev
• PHP的zip扩展依赖系统的libzip-dev，需要先安装该依赖再编译zip扩展

修正后的Dockerfile #

FROM php:8.1-fpm-alpine

# 安装系统依赖（包括PHP扩展编译所需的依赖）
RUN apk update && apk add --no-cache \
    linux-headers \
    libzip-dev \
    freetype-dev \
    libjpeg-turbo-dev \
    libpng-dev \
    && apk add --no-cache --virtual .build-deps ${PHPIZE_DEPS} \
    # 安装PHP扩展
    && docker-php-ext-install \
    exif \
    mysqli \
    pdo \
    pdo_mysql \
    zip \
    opcache \
    # 配置并安装gd扩展
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd \
    # 清理编译依赖，减小镜像体积
    && apk del .build-deps \
    && rm -rf /var/cache/apk/*

关键改动说明 #

• 将所有系统依赖包（libzip-dev、freetype-dev等）移到apk add命令中，用.build-deps虚拟包管理编译依赖，安装完成后删除以减小镜像体积
• PHP扩展列表里只保留官方内置扩展：把libzip换成正确的PHP扩展名zip，移除freetype、libfreetype6-dev等非PHP扩展项
• 调整执行顺序：先装系统依赖，再编译安装PHP扩展，最后清理无用文件
• 统一清理Alpine的apk缓存，进一步优化镜像大小

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