PHP Docker 镜像 (amd64)

镜像概述和主要用途

PHP 是一种为 Web 开发设计的服务器端脚本语言，也可用作通用编程语言。PHP 可以添加到纯 HTML 中，也可以与各种模板引擎和 Web 框架一起使用。PHP 代码通常由解释器处理，解释器既可以作为 Web 服务器上的原生模块实现，也可以作为通用网关接口 (CGI) 实现。

***.org/wiki/PHP

!logo

注意: 这是 php 官方镜像 的 amd64 架构构建版本。有关更多信息，请参阅官方镜像文档中的 "除 amd64 之外的架构？" 和官方镜像 FAQ 中的 "Git 中的镜像源已更改，现在该怎么办？"。

核心功能和特性

• 基于官方 PHP 源码构建，针对 amd64 架构优化
• 提供多种变体满足不同使用场景（CLI、Apache、FPM、Alpine 等）
• 内置扩展安装工具（docker-php-ext-configure、docker-php-ext-install、docker-php-ext-enable）
• 支持自定义 PHP 配置
• 包含开发和生产环境配置文件
• 可作为基础镜像构建自定义 PHP 环境

使用场景和适用范围

• Web 应用开发和部署
• 命令行脚本运行
• 微服务架构中的 PHP 服务
• CI/CD 流程中的 PHP 应用测试
• 本地开发环境一致性保障
• 生产环境 PHP 应用容器化部署

快速参考

• 维护者: Docker 社区

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

• 问题反馈: [***]

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

• 支持的标签: 请参见 [***]

详细使用方法和配置说明

基本用法

在 PHP 项目中创建 Dockerfile

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

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

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

运行单个 PHP 脚本

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

$ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/myapp -w /usr/src/myapp amd64/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 镜像的同一层中删除它。

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

PHP 核心扩展

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

FROM amd64/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 启用它：

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

FROM amd64/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 提供；也可以安装这些扩展，尽管过程自动化程度较低：

FROM amd64/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-* 脚本可以接受任意路径，但必须是绝对路径（以与内置扩展名区分），因此上述示例也可以写成以下形式：

FROM amd64/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）。

配置

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

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

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

示例

FROM amd64/php:8.2-fpm-alpine

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

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

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

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

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

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

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

镜像变体

amd64/php 镜像有多种风格，每种风格都设计用于特定用例。

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

amd64/php:<version>-cli

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

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

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

amd64/php:<version>-apache

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

使用 Dockerfile 的 Apache

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

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

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

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

不使用 Dockerfile 的 Apache

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

更改 DocumentRoot（或其他 Apache 配置）

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

FROM amd64/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 配置选项。

amd64/php:<version>-fpm

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

为了使用此镜像变体，需要某种反向代理（如 NGINX、Apache 或其他支持 FastCGI 协议的工具）。

一些可能有帮助的资源：

• FPM 的官方配置参考
• @md5 的简化示例
• Pascal Landau 的详细文章
• Stack Overflow 讨论
• Apache httpd Wiki 示例

警告： FastCGI 协议本质上是信任的，