ghcr.io/mlocati/php-extension-installer:2.11.19

在官方 PHP Docker 镜像中轻松安装 PHP 扩展

本仓库提供了一个脚本，可用于在https://hub.docker.com/_/php/内便捷安装 PHP 扩展。

该脚本会自动安装所有必需的 APT/APK 包；脚本执行完成后，所有不再需要的依赖包都会被移除，从而大幅缩小最终镜像体积。

支持的 Docker 镜像类型如下：

• 基于 Debian 的 Docker 镜像：最低支持从 jessie（Debian 8）开始（要求最低 PHP 版本为 5.5）
• 基于 Alpine 的 Docker 镜像：最低支持从 Alpine 3.9 开始（要求最低 PHP 版本为 7.1）

另请参阅特殊要求部分的说明。

使用方式

你可以通过多种方式在 Dockerfile 中使用此脚本。

以下是安装 GD 和 xdebug 这两个 PHP 扩展的 Dockerfile 示例列表：

使用 ADD 动态下载脚本

FROM php:7.2-cli

ADD --chmod=0755 https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug

使用 curl 动态下载脚本

FROM php:7.2-cli

RUN curl -sSLf \
-o /usr/local/bin/install-php-extensions \
https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions && \
chmod +x /usr/local/bin/install-php-extensions && \
install-php-extensions gd xdebug

使用 curl 直接执行脚本

FROM php:8.2-cli

RUN ( curl -sSLf https://github.com/mlocati/docker-php-extension-installer/releases/latest/download/install-php-extensions -o - || echo 'return 1' ) | sh -s \
gd xdebug

从 Docker 镜像中复制脚本

• 使用 GitHub Container Registry

FROM php:8.4-cli

COPY --from=ghcr.io/mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug

• 使用 Docker Hub

FROM php:8.4-cli

COPY --from=mlocati/php-extension-installer /usr/bin/install-php-extensions /usr/local/bin/

RUN install-php-extensions gd xdebug

[!WARNING] 使用该方法可能会用到已过期的 Docker 镜像版本。建议提前执行 docker pull ghcr.io/mlocati/php-extension-installer 或 docker pull mlocati/php-extension-installer 以拉取最新版本。

直接使用 Docker 镜像中的脚本

• 使用 GitHub Container Registry

RUN --mount=type=bind,from=ghcr.io/mlocati/php-extension-installer:latest,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
install-php-extensions gd xdebug

• 使用 Docker Hub

RUN --mount=type=bind,from=mlocati/php-extension-installer:latest,source=/usr/bin/install-php-extensions,target=/usr/local/bin/install-php-extensions \
install-php-extensions gd xdebug

[!WARNING] 使用该方法可能会用到已过期的 Docker 镜像版本。建议提前执行 docker pull ghcr.io/mlocati/php-extension-installer 或 docker pull mlocati/php-extension-installer 以拉取最新版本。

安装扩展的指定版本

只需在扩展模块名称后追加 - 和版本号即可。例如：

install-php-extensions xdebug-2.9.7

该脚本还支持通过在版本号前添加脱字符（^）来自动解析兼容版本。例如：

# 安装 xdebug 2.x 的最新版本（例如 2.9.8）
install-php-extensions xdebug-^2
# 安装 xdebug 2.8.x 的最新版本（例如 2.8.1）
install-php-extensions xdebug-^2.8

请注意，使用上述语法时你将获取最新的兼容版本，该版本可能为非稳定版。如果希望安装最新的稳定版本，可以在末尾追加 @stable：

# 安装 xdebug 3.x 的最新 STABLE 版本（例如 3.2.2）
install-php-extensions xdebug-^3@stable

可用的稳定性后缀包括：@snapshot、@devel、@alpha、@beta 和 @stable。

对于 PECL 上提供的预发布版本扩展，你可以在扩展名称后直接追加其状态标识，例如 alpha、beta、rc、preview、devel 或 snapshot 来安装对应版本。例如：

install-php-extensions xdebug-beta

[!NOTE] 当 PECL 上的最新可用版本为非稳定版，而你希望保留上一个稳定版本时，可以在扩展名称后添加 stable 后缀来强制指定。例如：

> install-php-extensions mongodb-stable
>

从源代码安装扩展

你也可以从源代码安装 PHP 扩展，前提是源代码包中包含 package.xml 或 package2.xml 文件。

支持的源格式包括：

• GitHub 托管仓库的短格式写法。 例如，对于 https://github.com/php-memcached-dev/php-memcached 这个 GitHub 仓库，你可以直接使用以下写法：

# 从指定提交（完整 SHA-1 哈希值）安装
  install-php-extensions php-memcached-dev/php-memcached@8f106564e6bb005ca6100b12ccc89000daafa9d8
  # 从指定提交（短 SHA-1 哈希值）安装
  install-php-extensions php-memcached-dev/php-memcached@8f106564e6bb
  # 从 v3.2.0RC2 标签安装
  install-php-extensions php-memcached-dev/php-memcached@v3.2.0RC2
  install-php-extensions php-memcached-dev/php-memcached@refs/tags/v3.2.0RC2
  # 从 master 分支安装
  install-php-extensions php-memcached-dev/php-memcached@master
  install-php-extensions php-memcached-dev/php-memcached@refs/heads/master

• 提供源代码压缩包的 URL 地址。 示例如下：

# 提交 8f106564e6bb005ca6100b12ccc89000daafa9d8 对应的 tgz 压缩包
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/8f106564e6bb005ca6100b12ccc89000daafa9d8
  # 标签 v3.1.5 对应的 tgz 压缩包
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/tags/v3.1.5
  # master 分支对应的 tgz 压缩包
  install-php-extensions https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/heads/master

• 本地目录的绝对路径。 示例如下：

# 下载源代码
  curl -o /tmp/source.tgz https://codeload.github.com/php-memcached-dev/php-memcached/tar.gz/refs/tags/v3.1.5
  tar xzf /tmp/source.tgz -C /tmp
  install-php-extensions /tmp/php-memcached-3.1.5

扩展是 PHP 内置捆绑的吗？

部分 PHP 扩展是随 PHP 源代码一起捆绑发布的，例如 gd 和 zip。

其中部分扩展同时也在 PECL 和/或独立源代码仓库中提供。

默认情况下，install-php-extensions 会优先安装 PHP 源代码中内置的捆绑版本。

如果你希望使用远程提供的版本：

• 对于使用 PECL 版本：只需在包名后追加稳定性状态即可。例如：

install-php-extensions zip-stable

• 对于从源代码安装：使用上述指定的语法即可。例如：

install-php-extensions php/pecl-database-oci8@7aa1061

install-php-extensions 支持为以下扩展安装远程版本，而非内置捆绑版本：

• pdo_oci
• oci8
• zip

安装 composer

你也可以安装 https://getcomposer.org/，同时支持指定其主版本号或完整版本号。

使用示例：

# 安装最新版本
install-php-extensions @composer
# 安装 1.x 系列的最新版本
install-php-extensions @composer-1
# 安装指定的具体版本
install-php-extensions @composer-2.0.2

Let's Encrypt 证书相关问题

Let's Encrypt 的根 CA 证书已发生变更（https://letsencrypt.org/docs/dst-root-ca-x3-expiration-september-2021/），该变更会导致以下老旧 Linux 发行版出现问题：

• Debian Jessie (8)
• Debian Stretch (9)
• Alpine Linux 3.7
• Alpine Linux 3.8

你可以通过该脚本修复该问题：只需传入 @fix_letsencrypt 作为参数即可：

install-php-extensions @fix_letsencrypt

支持的 PHP 扩展

以下是 ghcr.io/mlocati/php-extension-installer 镜像（参考标签：latest）支持的 PHP 扩展与各版本兼容对照表，勾选标记表示该扩展可在对应 PHP 版本中正常安装使用：

支持的扩展数量：162

注：预安装的 PHP 扩展不计入此列表。 你可以使用以下命令列出这些预安装扩展（请将 php:8.5-cli 替换为你需要的 PHP 版本）：

$ docker run --rm php:8.5-cli php -m
[PHP Modules]
Core
ctype
curl
date
dom
fileinfo
filter
hash
iconv
json
lexbor
libxml
mbstring
mysqlnd
openssl
pcre
PDO
pdo_sqlite
Phar
posix
random
readline
Reflection
session
SimpleXML
sodium
SPL
sqlite3
standard
tokenizer
uri
xml
xmlreader
xmlwriter
Zend OPcache
zlib

[Zend Modules]
Zend OPcache

配置

你可以通过环境变量配置该脚本的行为，并针对部分扩展进行精细调整，以满足你的使用需求。

以下是配置示例：

IPE_LZF_BETTERCOMPRESSION=1 install-php-extensions lzf

所有支持的环境变量如下表所示：

特殊要求

部分扩展存在特殊使用要求：

如何查看当前使用的 Linux 发行版？

你可以运行以下命令：

cat /etc/os-release

示例输出：

• 对于 Debian 11（Bullseye），输出结果如下：

PRETTY_NAME="Debian GNU/Linux 11 (bullseye)"

• 对于 Alpine Linux 3.14，输出结果如下：

PRETTY_NAME="Alpine Linux v3.14"

库版本

部分 PHP 扩展依赖的系统库如果未在系统预设环境中提供，install-php-extensions 会自动编译或下载对应库。你可以通过设置对应的环境变量，指定使用非默认版本的库。例如：

IPE_LIBVERSION_XCRYPT=4.4.36 install-php-extensions xpass

[!WARNING] 非默认版本的库可能无法正常工作，使用该功能的风险需由你自行承担。

以下是相关库的完整列表（默认版本为当前最新版 install-php-extensions 所使用的版本）：

ghcr.io/mlocati/php-extension-installer 参考标签：latest

测试

在提交拉取请求时，系统会运行一个 https://github.com/mlocati/docker-php-extension-installer/blob/master/.github/workflows/test-extensions.yml，用于验证受影响的 PHP 扩展是否可正常工作（详见下文）。

此外，我们还会验证新版本 PHP 扩展及其依赖库是否仍可正常使用。 这项工作会通过另一个 https://github.com/mlocati/docker-php-extension-installer/blob/master/.github/workflows/check-updates.yml 按计划定期执行。 如果执行失败，系统会向一个 *** 频道 发送消息。 你可以自由订阅该频道，接收失败通知。

如何贡献

请参阅 https://github.com/mlocati/docker-php-extension-installer/blob/master/CONTRIBUTING.md 文件。

维护人员须知

请参阅 https://github.com/mlocati/docker-php-extension-installer/blob/master/MAINTAINERS.md 文件。

想要表达谢意？

你可以请我喝杯 https://github.com/***/mlocati 或者 单次咖啡 :wink: