i386/php 镜像文档

镜像概述和主要用途

i386/php 是 PHP ***镜像的 i386 架构专用版本。PHP 是一种服务器端脚本语言，主要设计用于 Web 开发，但也可用作通用编程语言。PHP 代码通常由解释器处理，解释器既可以实现为 Web 服务器上的原生模块，也可以作为通用网关接口 (CGI) 实现。

注意：这是 php 镜像 的 "per-architecture" i386 构建版本仓库。有关更多信息，请参阅镜像文档中的 "除 amd64 之外的架构？" 和***镜像 FAQ 中的 "Git 中镜像的源代码已更改，现在该怎么办？"。

!logo

核心功能和特性

• 基于 PHP ***源代码构建，确保原汁原味的 PHP 运行环境
• 包含多种变体，适用于不同场景（CLI、Apache、FPM、Alpine 等）
• 提供工具脚本简化 PHP 扩展的安装与配置（docker-php-ext-configure、docker-php-ext-install、docker-php-ext-enable 等）
• 支持自定义 PHP 配置，可轻松覆盖默认配置
• 体积优化，同时保持功能完整性
• 多架构支持，本镜像专注于 i386 架构

使用场景和适用范围

• 开发和运行 PHP 应用程序
• 构建基于 PHP 的 Web 应用服务
• 创建自定义 PHP 运行环境
• 快速测试 PHP 脚本或应用
• CI/CD 流程中的 PHP 环境提供
• 需要 i386 架构支持的特定场景

快速参考

• 维护者：
  Docker 社区

• 获取帮助：
  Docker 社区 Slack、Server Fault、Unix & Linux 或 Stack Overflow

• 提交问题：
  [***]

• 支持的架构：(更多信息)
  amd64、arm32v5、arm32v6、arm32v7、arm64v8、i386、mips64le、ppc64le、riscv64、s390x

• 镜像更新：
  official-images 仓库的 library/php 标签
  official-images 仓库的 library/php 文件 (历史记录)

支持的标签和对应的 Dockerfile 链接

注意：此镜像的描述超出了 Hub 的 25000 字符长度限制，因此"支持的标签"列表已被截断以适应。另请参见 docker/hub-feedback#238 和 docker/roadmap#475。

• 详见 [***] 中的"支持的标签和对应的 Dockerfile 链接"

使用方法和配置说明

基本使用方法

在 PHP 项目中创建 Dockerfile

dockerfile
FROM i386/php:8.2-cli
COPY . /usr/src/myapp
WORKDIR /usr/src/myapp
CMD [ "php", "./your-script.php" ]

然后，运行以下命令构建并运行 Docker 镜像：

console
$ docker build -t my-php-app .
$ docker run -it --rm --name my-running-app my-php-app

运行单个 PHP 脚本

对于许多简单的单文件项目，编写完整的 Dockerfile 可能不方便。在这种情况下，可以直接使用 PHP Docker 镜像运行 PHP 脚本：

console
$ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/myapp -w /usr/src/myapp i386/php:8.2-cli php your-script.php

如何安装更多 PHP 扩展

许多扩展已经编译到镜像中，因此在费力编译更多扩展之前，值得检查 php -m 或 php -i 的输出。

我们提供了帮助脚本 docker-php-ext-configure、docker-php-ext-install 和 docker-php-ext-enable，以便更轻松地安装 PHP 扩展。

为了保持镜像较小，PHP 源代码保存在压缩的 tar 文件中。为了便于将 PHP 源代码与任何扩展链接，我们还提供了帮助脚本 docker-php-source，以轻松提取 tar 文件或删除提取的源代码。注意：如果使用 docker-php-source 提取源代码，请确保在 docker 镜像的同一层中删除它。

Dockerfile
FROM i386/php:8.2-cli
RUN docker-php-source extract \
	# 执行重要操作 \
	&& docker-php-source delete

PHP 核心扩展

例如，如果需要带有 gd 扩展的 PHP-FPM 镜像，可以继承喜欢的基础镜像，并编写自己的 Dockerfile，如下所示：

dockerfile
FROM i386/php:8.2-fpm
RUN apt-get update && apt-get install -y \
		libfreetype-dev \
		libjpeg62-turbo-dev \
		libpng-dev \
	&& docker-php-ext-configure gd --with-freetype --with-jpeg \
	&& docker-php-ext-install -j$(nproc) gd

请记住，必须手动安装扩展的依赖项。如果扩展需要自定义 configure 参数，可以像此示例一样使用 docker-php-ext-configure 脚本。在这种情况下，无需手动运行 docker-php-source，因为 configure 和 install 脚本会处理它。

如果难以确定在 docker-php-ext-install 之前需要安装哪些 Debian 或 Alpine 软件包，可以查看 install-php-extensions 项目。此脚本基于 docker-php-ext-* 脚本构建，通过自动添加和删除 Debian (apt) 和 Alpine (apk) 软件包，简化了 PHP 扩展的安装。例如，要安装 GD 扩展，只需运行 install-php-extensions gd。此工具由社区成员贡献，不包含在镜像中，请参阅其 Git 仓库了解安装、使用和问题。

默认扩展

某些扩展默认情况下已编译。这取决于所使用的 PHP 版本。在容器中运行 php -m 以获取特定版本的列表。

PECL 扩展

有些扩展未随 PHP 源代码一起提供，而是可通过 PECL 获取。要安装 PECL 扩展，请使用 pecl install 下载并编译它，然后使用 docker-php-ext-enable 启用它：

dockerfile
FROM i386/php:8.2-cli
RUN pecl install redis-5.3.7 \
	&& pecl install xdebug-3.2.1 \
	&& docker-php-ext-enable redis xdebug

dockerfile
FROM i386/php:8.2-cli
RUN apt-get update && apt-get install -y libmemcached-dev libssl-dev zlib1g-dev \
	&& pecl install memcached-3.2.0 \
	&& docker-php-ext-enable memcached

强烈建议用户在 pecl install 调用中使用显式版本号，以确保适当的 PHP 版本兼容性（PECL 在选择要安装的扩展版本时不检查 PHP 版本兼容性，但在尝试安装时会检查）。除了兼容性问题外，确保知道依赖项何时接收更新并可以直接控制这些更新也是一个好***惯。

与 PHP 核心扩展不同，PECL 扩展应串行安装，以便在出现问题时正确失败。否则，PECL 会跳过错误。例如，使用 pecl install memcached-3.2.0 && pecl install redis-5.3.7，而不是 pecl install memcached-3.2.0 redis-5.3.7。但是，docker-php-ext-enable memcached redis 可以在一个命令中完成。

其他扩展

有些扩展不通过 Core 或 PECL 提供；这些也可以安装，尽管过程不太自动化：

dockerfile
FROM i386/php:8.2-cli
RUN curl -fsSL '[自定义PHP模块的URL]' -o module-name.tar.gz \
	&& mkdir -p module-name \
	&& sha256sum -c "[shasum值]  module-name.tar.gz" \
	&& tar -xf module-name.tar.gz -C module-name --strip-components=1 \
	&& rm module-name.tar.gz \
	&& ( \
		cd module-name \
		&& phpize \
		&& ./configure --enable-module-name \
		&& make -j "$(nproc)" \
		&& make install \
	) \
	&& rm -r module-name \
	&& docker-php-ext-enable module-name

docker-php-ext-* 脚本可以接受任意路径，但必须是绝对路径（以消除与内置扩展名称的歧义），因此上述示例也可以写成以下形式：

dockerfile
FROM i386/php:8.2-cli
RUN curl -fsSL '[自定义PHP模块的URL]' -o module-name.tar.gz \
	&& mkdir -p /tmp/module-name \
	&& sha256sum -c "[shasum值]  module-name.tar.gz" \
	&& tar -xf module-name.tar.gz -C /tmp/module-name --strip-components=1 \
	&& rm module-name.tar.gz \
	&& docker-php-ext-configure /tmp/module-name --enable-module-name \
	&& docker-php-ext-install /tmp/module-name \
	&& rm -r /tmp/module-name

以任意用户身份运行

要以任意用户身份运行 Apache 变体，有几种选择：

• 如果内核 版本为 4.11 或更高，可以添加 --sysctl net.ipv4.ip_unprivileged_port_start=0（这将是 Docker 未来版本的默认设置），然后 --user 应该像对 FPM 那样工作。
• 如果将 Apache 配置调整为使用"非特权"端口（默认情况下大于 1024），则无论内核版本如何，--user 都应该像对 FPM 那样工作。

要以任意用户身份运行 FPM 变体，应使用 docker run 的 --user 标志（可以接受容器的 /etc/passwd 文件中的用户名/组，如 --user daemon，或特定的 UID/GID，如 --user 1000:1000）。

"E: Package 'php-XXX' has no installation candidate" 错误处理

从 docker-library/php#542 开始，此镜像阻止安装 Debian 的 PHP 软件包。在 docker-library/php#551 (comment) 中有关于此更改的更多讨论，但要点是在此镜像中安装 Debian 的 PHP 软件包会导致在单个镜像中存在两个冲突的 PHP 安装，这几乎肯定不是预期的结果。

对于那些因此更改而遇到问题并正在寻找临时解决方法的用户，在开发适当修复程序时，将以下简单行添加到 Dockerfile 应该可以删除阻止（强烈警告：这将允许安装第二个 PHP 安装，除非您确实知道自己在做什么，否则这绝对不是您想要的）：

dockerfile
RUN rm /etc/apt/preferences.d/no-debian-php

此错误的正确解决方案是要么使用 FROM debian:XXX 并直接安装 Debian 的 PHP 软件包，要么使用 docker-php-ext-install、pecl 和/或 phpize 安装必要的附加扩展和实用程序。

配置

此镜像附带默认的 php.ini-development 和 php.ini-production 配置文件。

强烈建议在生产环境中使用的镜像使用生产配置！

可以通过将配置文件复制到 $PHP_INI_DIR/conf.d/ 目录来自定义默认配置。

示例

dockerfile
FROM i386/php:8.2-fpm-alpine

# 使用默认的生产配置
RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

在许多生产环境中，还建议（构建并）启用 PHP 核心 OPcache 扩展以提高性能。有关更多详细信息，请参阅 上游 OPcache 文档。

镜像变体

i386/php 镜像有多种版本，每种版本都设计用于特定用例。

有些标签可能包含 bookworm 或 trixie 等名称。这些是 Debian 版本的套件代码名称，表示镜像所基于的发行版。如果您的镜像需要安装超出镜像自带的任何其他软件包，您可能需要明确指定其中之一，以最大程度地减少 Debian 有新版本时的中断。

i386/php:<version>-cli

此变体包含 PHP CLI 工具和默认模块。如果需要 Web 服务器，这可能不是您要找的镜像。它设计用于作为一次性容器（挂载源代码并启动容器以启动应用程序），以及作为构建其他镜像的基础。

它也是唯一包含（不推荐的）php-cgi 二进制文件的变体，这对于某些事情（如 PPM）可能是必要的。

请注意，i386/php 的所有变体都包含 PHP CLI (/usr/local/bin/php)。

i386/php:<version>-apache

此镜像包含 Debian 的 Apache httpd 以及 PHP（作为 mod_php），默认使用 mpm_prefork。

使用 Dockerfile 的 Apache

dockerfile
FROM i386/php:7.2-apache
COPY src/ /var/www/html/

其中 src/ 是包含所有 PHP 代码的目录。然后，运行以下命令构建并运行 Docker 镜像：

console
$ docker build -t my-php-app .
$ docker run -d --name my-running-app my-php-app

我们建议添加 php.ini 配置文件；有关详细信息，请参阅"配置"部分。

不使用 Dockerfile 的 Apache

console
$ docker run -d -p 80:80 --name my-apache-php-app -v "$PWD":/var/www/html i386/php:7.2-apache

更改 DocumentRoot（或其他 Apache 配置）

某些应用程序可能希望更改 Apache 中的默认 DocumentRoot（远离 /var/www/html）。以下演示了使用环境变量的一种方法（也可以在容器运行时修改）：

dockerfile
FROM i386/php:7.1-apache

ENV APACHE_DOCUMENT_ROOT /path/to/new/root

RUN sed -ri -e 's!/var/www/html!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/sites-available/*.conf
RUN sed -ri -e 's!/var/www/!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf

类似的技术也可用于其他 Apache 配置选项。

i386/php:<version>-fpm

此变体包含 PHP 的 FastCGI 进程管理器 (FPM)，这是 PHP 推荐的 FastCG