i386/php

i386/php 镜像文档

镜像概述和主要用途

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

注意：这是 https://hub.docker.com/_/php 的 "per-architecture" i386 构建版本仓库。有关更多信息，请参阅官方镜像文档中的 https://github.com/docker-library/official-images#architectures-other-than-amd64 和官方镜像 FAQ 中的 https://github.com/docker-library/faq#an-images-source-changed-in-git-now-what%E3%80%82

!https://raw.githubusercontent.com/docker-library/docs/01c***b2fe592c1f93a13b4e289ada0e3a1/php/logo.png

核心功能和特性

• 基于 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 架构支持的特定场景

快速参考

• 维护者：
  https://github.com/docker-library/php

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

• 提交问题：
  https://github.com/docker-library/php/issues?q=

• 支持的架构：(https://github.com/docker-library/official-images#architectures-other-than-amd64)
  https://hub.docker.com/r/amd64/php/%E3%80%81https://hub.docker.com/r/arm32v5/php/%E3%80%81https://hub.docker.com/r/arm32v6/php/%E3%80%81https://hub.docker.com/r/arm32v7/php/%E3%80%81https://hub.docker.com/r/arm64v8/php/%E3%80%81https://hub.docker.com/r/i386/php/%E3%80%81https://hub.docker.com/r/mips64le/php/%E3%80%81https://hub.docker.com/r/ppc64le/php/%E3%80%81https://hub.docker.com/r/riscv64/php/%E3%80%81https://hub.docker.com/r/s390x/php/

• 镜像更新：
  https://github.com/docker-library/official-images/issues?q=label%3Alibrary%2Fphp
  https://github.com/docker-library/official-images/blob/master/library/php (https://github.com/docker-library/official-images/commits/master/library/php)

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

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

• 详见 https://github.com/docker-library/docs/tree/master/php/README.md#supported-tags-and-respective-dockerfile-links 中的"支持的标签和对应的 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 软件包，可以查看 https://github.com/mlocati/docker-php-extension-installer%E3%80%82%E6%AD%A4%E8%84%9A%E6%9C%AC%E5%9F%BA%E4%BA%8E 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 变体，有几种选择：

• 如果内核 https://github.com/moby/moby/issues/8460#issuecomment-312459310%EF%BC%8C%E5%8F%AF%E4%BB%A5%E6%B7%BB%E5%8A%A0 --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" 错误处理

从 https://github.com/docker-library/php/pull/542 开始，此镜像阻止安装 Debian 的 PHP 软件包。在 https://github.com/docker-library/php/issues/551#issuecomment-354849074 中有关于此更改的更多讨论，但要点是在此镜像中安装 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 安装必要的附加扩展和实用程序。

配置

此镜像附带默认的 https://github.com/php/php-src/blob/master/php.ini-development 和 https://github.com/php/php-src/blob/master/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 二进制文件的变体，这对于某些事情（如 https://github.com/php-pm/php-pm%EF%BC%89%E5%8F%AF%E8%83%BD%E6%98%AF%E5%BF%85%E8%A6%81%E7%9A%84%E3%80%82

请注意，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