amd64/php

PHP Docker 镜像 (amd64)

镜像概述和主要用途

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

***.org/wiki/PHP

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

注意: 这是 https://hub.docker.com/_/php 的 amd64 架构构建版本。有关更多信息，请参阅官方镜像文档中的 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

核心功能和特性

• 基于官方 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 应用容器化部署

快速参考

• 维护者: 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/docs/tree/master/php/README.md#supported-tags-and-respective-dockerfile-links

详细使用方法和配置说明

基本用法

在 PHP 项目中创建 Dockerfile

dockerfile
FROM amd64/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 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 镜像的同一层中删除它。

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

PHP 核心扩展

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

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 软件包，请查看 https://github.com/mlocati/docker-php-extension-installer%E3%80%82%E8%AF%A5%E8%84%9A%E6%9C%AC%E5%BB%BA%E7%AB%8B%E5%9C%A8 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 amd64/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 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 提供；也可以安装这些扩展，尽管过程自动化程度较低：

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

dockerfile
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 变体，有几种选择：

• 如果内核 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）。

配置

此镜像附带默认的 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 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" 错误

从 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 安装必要的附加扩展和工具。

镜像变体

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

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

amd64/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

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

amd64/php:<version>-apache

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

使用 Dockerfile 的 Apache

dockerfile
FROM amd64/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 amd64/php:7.2-apache

更改 DocumentRoot（或其他 Apache 配置）

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

dockerfile
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 的官方配置参考
• https://gist.github.com/md5/d9206eacb5a0ff5d6be0
• Pascal Landau 的详细文章
• Stack Overflow 讨论
• Apache httpd Wiki 示例

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