Docker镜像安装失败：php-ext-install执行出错（WSL2环境）

环境信息 #

• Windows 10 + WSL2
• Docker版本：4.9.0（80466）、4.11
• 基础镜像：php:7.4-cli-alpine

错误现象 #

执行docker-php-ext-install ctype exif gd iconv simplexml zip时编译失败，返回错误码2，核心错误日志片段：

/usr/src/php/ext/iconv/iconv.c:284:25: error: '_libiconv_version' undeclared (first use in this function)
/usr/src/php/ext/iconv/iconv.c:181:15: warning: implicit declaration of function 'libiconv'; did you mean 'iconv'? [-Wimplicit-function-declaration]

解决方案 #

问题根源是Alpine默认的musl libc自带iconv与PHP扩展依赖的GNU libiconv不兼容，需安装GNU版本libiconv并预加载：

修改后的完整Dockerfile #

ARG PHP_VERSION=7.4

FROM php:${PHP_VERSION}-cli-alpine AS betl
# 合并安装基础依赖与gnu-libiconv
RUN apk add --no-cache \
        zip \
        zlib-dev \
        openssh \
        rsync \
        freetype-dev \
        libjpeg-turbo-dev \
        libpng-dev \
        libxml2-dev \
        libzip-dev \
        git \
        libssh2-dev \
        autoconf \
        build-base \
        jpeg-dev \
    && apk add --no-cache --repository http://dl-cdn.alpinelinux.org/alpine/v3.13/community/ gnu-libiconv=1.15-r3

# 预加载GNU libiconv，确保PHP优先使用该库
ENV LD_PRELOAD /usr/lib/preloadable_libiconv.so php

# 批量安装PHP扩展，减少镜像层数
RUN docker-php-ext-install ctype exif gd iconv simplexml zip \
    && docker-php-ext-configure gd --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd \
    && pecl install ssh2-1.3.1 \
    && docker-php-ext-enable ssh2

# Composer环境配置
ENV COMPOSER_HOME /composer
ENV COMPOSER_ALLOW_SUPERUSER 1
ENV PATH /composer/vendor/bin:$PATH
ENV PHP_CONF_DIR=/usr/local/etc/php/conf.d

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

RUN echo "memory_limit=-1" > $PHP_CONF_DIR/99_memory-limit.ini

WORKDIR /betl

ENTRYPOINT ["sh", "./bin/lconsole"]

关键说明 #

1. 安装gnu-libiconv：Alpine 3.14及以上版本仓库已移除该包，因此指定v3.13社区仓库获取兼容版本
2. LD_PRELOAD设置：强制PHP进程优先加载GNU libiconv库，规避musl版本的API缺失问题
3. 合并镜像层：将多次apk add和扩展安装命令合并，减少镜像体积与构建时间

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