为 Docker 中的 PHP 8.2 添加 GD 扩展:Alpine 镜像实战记录

今天在一次给图像工具做部署排错的过程中,完整走了一遍「发现缺扩展 → 容器内临时安装 → 写入 Dockerfile 持久化 → 填平 Alpine 专属大坑」的流程。本文把可复用的步骤和踩过的坑整理出来,如果你也在用官方 php:*-alpine 镜像,应该能少走不少弯路。

环境信息

项目值
PHP 版本8.2
Docker 镜像php:8.2-fpm-alpine(Alpine Linux 基础)
容器名myphp
编排方式docker-compose.yml,服务通过 external 网络供 Caddy 反向代理

Alpine 镜像以体积小著称(整个镜像只有几十 MB),但它用的是 apk 包管理器而非 Debian 系的 apt-get,而且系统库极简——这正是后面编译扩展时要额外装依赖的原因。

第一步:确认问题

应用的上传接口返回了 500:

{"ok":false,"error":"服务器缺少 GD 扩展,无法处理图像。"}

进容器确认:

docker exec myphp php -m | grep -i gd
# 无输出 → GD 确实没装

第二步:容器内临时安装 GD

官方 PHP 镜像自带一组便捷脚本:docker-php-ext-configure、docker-php-ext-install、docker-php-ext-enable。安装扩展的套路就是「装系统依赖 → 配置 → 编译安装」。

Alpine 下,GD 需要几个图像库的开发包:

docker exec -it myphp sh -c '
apk add --no-cache \
  libpng-dev \
  libjpeg-turbo-dev \
  freetype-dev \
  libwebp-dev \
&& docker-php-ext-configure gd \
  --with-freetype \
  --with-jpeg \
  --with-webp \
&& docker-php-ext-install -j"$(nproc)" gd
'

几个要点:

  • --no-cache:apk 不保留索引缓存,镜像更干净。
  • 四个库对应四种能力:libpng(PNG)、libjpeg-turbo(JPEG)、freetype(字体)、libwebp(WebP)。缺哪个,对应格式就解码不了。
  • 参数写法有版本分水岭:PHP 7.4 起用 --with-freetype --with-jpeg --with-webp;PHP 7.3 及更早要写成 --with-freetype-dir --with-jpeg-dir --with-webp-dir。我们是 8.2,用新写法,别照抄网上的老教程。
  • -j"$(nproc)":按 CPU 核数并行编译,快很多。

安装完验证:

docker exec myphp php -m | grep -i gd          # 输出 gd
docker exec myphp php -i | grep -iE 'GD Support|JPEG|WebP|FreeType'
# GD Support => enabled / JPEG Support => enabled / WebP Support => enabled ...

到这一步,当前容器已经能用 GD 了。但容器一旦重建,这些改动全部丢失——因为手动安装的改动只存在于容器的可写层。必须做持久化。

第三步:持久化 —— 写进 Dockerfile

在 docker-compose.yml 所在目录创建 Dockerfile:

FROM php:8.2-fpm-alpine

RUN apk add --no-cache \
      libpng-dev \
      libjpeg-turbo-dev \
      freetype-dev \
      libwebp-dev \
    && docker-php-ext-configure gd \
        --with-freetype \
        --with-jpeg \
        --with-webp \
    && docker-php-ext-install -j"$(nproc)" gd

把 compose 里的服务从「直接拉镜像」改为「用 Dockerfile 构建」:

services:
  php:
    build: .                       # 用当前目录的 Dockerfile 构建
    image: myphp:8.2-fpm-gd        # 构建产物的镜像名(可自定义)
    container_name: myphp
    restart: unless-stopped
    volumes:
      - ~/caddy/site/site1:/var/html/site1
      - ~/php/php-config:/usr/local/etc/php
    networks:
      - php-network

networks:
  php-network:
    external: true

关键变化只有两处:image: 换成 build: .,再补一个 image: 作为构建标签。其余卷挂载、网络保持原样。

然后构建并重启:

docker compose up -d --build

第四步:Alpine 专属大坑 —— 挂载覆盖了 conf.d

这是今天最隐蔽的一个问题,值得单独讲。

我的 compose 里挂载了:

- ~/php/php-config:/usr/local/etc/php

docker-php-ext-install gd 会在镜像内的 /usr/local/etc/php/conf.d/ 下生成一个 docker-php-ext-gd.ini(内容就是 extension=gd),PHP 启动时靠它加载 GD 模块。但这个挂载把整个 /usr/local/etc/php 目录替换成了宿主机目录——镜像里生成的 ini 被挡住了,PHP 根本不知道要加载 GD。

结果就是:明明镜像里编译好了 GD,服务却报「找不到扩展」。

解决办法是在宿主机的挂载目录里补上这个 ini:

echo "extension=gd" > ~/php/php-config/conf.d/gd.ini

顺带把应用的上传限制也放进宿主机的 php.ini(因为同样被挂载覆盖):

upload_max_filesize = 13M
post_max_size = 16M
memory_limit = 256M

记住这条通用原则:凡是挂载覆盖了 /usr/local/etc/php,镜像内生成的所有 ini 配置都会失效,必须在宿主机挂载目录里重建。这是「官方 PHP 镜像 + 自定义配置挂载」组合的高频坑,不只是 GD 会遇到。

第五步:最终验证

# 1. 模块已加载
docker exec myphp php -m | grep -i gd

# 2. 容器内配置生效
docker exec myphp php -i | grep -i 'Loaded Configuration File'

# 3. 重建容器后依然可用(验证持久化是否真的成功)
docker compose down && docker compose up -d --build
docker exec myphp php -m | grep -i gd

第 3 步才是持久化的真正考验——如果重建后 GD 还在,说明配置已经固化进镜像和挂载,一劳永逸。

附:今天顺带踩的两个应用级坑

虽然不属于「装扩展」本身,但既然是同一天的排错,一并记录:

1. 上传报 400,根因是 tmp/ 目录权限

报错 move_uploaded_file(): Failed to open stream: Permission denied。容器里 PHP-FPM 默认以 www-data(Alpine 下 UID 82)运行,宿主机挂载的 tmp/ 目录属主不匹配。修复:

mkdir -p /绝对路径/caddy/site/site1/skymirror/tmp
chmod 777 /绝对路径/caddy/site/site1/skymirror/tmp
# 或更精细:chown 82:82 ./tmp && chmod 775 ./tmp

注意 compose 里的 ~ 指的是执行 docker compose 那个用户的 home,务必用绝对路径操作,避免 home 不一致导致改错目录。

2. 响应体混入 PHP 警告,前端报 Unexpected token '<'

PHP 默认把 Warning 以 <br /><b>Warning</b>... 的 HTML 形式直接打印到响应里,污染了本应是 JSON 的接口返回。在 api.php 顶部加两行即可根治:

ini_set('display_errors', '0');
error_reporting(E_ALL);

既不向客户端输出错误 HTML,又保留错误到日志,便于排查。

小结

为 Docker 中的 PHP 添加 GD 扩展,完整链路是:

flowchart LR
    A[发现缺 GD] --> B[容器内 apk 装依赖]
    B --> C[configure + install]
    C --> D[验证模块加载]
    D --> E[写入 Dockerfile 持久化]
    E --> F[compose 改 build]
    F --> G{有挂载覆盖<br>/usr/local/etc/php?}
    G -- 是 --> H[宿主机补 conf.d/gd.ini]
    G -- 否 --> I[构建并重启]
    H --> I
    I --> J[重建容器复验]

三个最容易翻车的点:

  1. Alpine 用 apk 且需额外装 *-dev 库,参数写法认准 PHP 7.4+ 的新格式;
  2. 手动安装不持久,一定要落到 Dockerfile 并改用 build;
  3. 挂载覆盖 /usr/local/etc/php 会让镜像内的 ini 失效,必须在宿主机重建配置。

把这三件事记住,以后在任何官方 PHP 镜像里装扩展,都是同一套心法。