如何为PHP项目编写Dockerfile？

wen PHP项目 2026-06-19 2

如何为PHP项目编写Dockerfile：从入门到生产级实践

目录导读

为什么PHP项目需要Dockerfile？
基础Dockerfile结构解析
开发环境Dockerfile编写
生产环境多阶段构建优化
常用扩展与配置实战
性能与安全最佳实践
常见问题问答（FAQ）

为什么PHP项目需要Dockerfile？

在传统PHP开发中，环境不一致（如本地PHP 7.4 vs 生产8.1）常导致“在我机器上能跑”的困境，Dockerfile通过声明式定义PHP运行环境（包括扩展、Composer依赖、Web服务器配置），确保开发、测试、生产环境完全一致，据统计，采用容器化部署的PHP项目，环境类Bug减少约67%。

如何为PHP项目编写Dockerfile？

基础Dockerfile结构解析

一个典型PHP Dockerfile包含以下核心指令：

FROM php:8.2-fpm-alpine   # 基础镜像：轻量化Alpine + PHP-FPM
WORKDIR /var/www/html      # 工作目录
COPY . .                    # 复制项目文件
RUN docker-php-ext-install pdo_mysql  # 安装PHP扩展
EXPOSE 9000                 # 暴露PHP-FPM端口
CMD ["php-fpm"]            # 容器启动命令

关键点：

选择-fpm镜像可与Nginx配合
-alpine版本比普通镜像小80%（约20MB vs 100MB）
使用docker-php-ext-*官方脚本简化扩展安装

阶段一：开发环境Dockerfile编写

1 必备扩展安装

PHP项目通常需要以下扩展（以Laravel为例）：

FROM php:8.2-fpm-alpine
# 安装系统依赖（GD库需libpng，Zip需libzip）
RUN apk add --no-cache libpng-dev libzip-dev
# 安装PHP扩展
RUN docker-php-ext-install pdo_mysql bcmath gd zip opcache
# 安装Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
WORKDIR /var/www/html
COPY . .
RUN composer install --no-dev --optimize-autoloader

注意：开发环境可加入xdebug扩展（使用pecl install xdebug）,但生产环境必须移除。

2 非root用户安全配置

RUN addgroup -g 1000 -S www && \
    adduser -u 1000 -S www -G www
USER www

避免容器以root运行,降低安全风险。

阶段二：生产环境多阶段构建优化

1 为什么需要多阶段？

单阶段Dockerfile会导致：

镜像体积大（包含构建工具如Composer、Git）
暴露源码历史文件

2 完整生产级Dockerfile示例

# 第一阶段：构建依赖
FROM composer:2.6 AS builder
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --no-interaction
# 第二阶段：运行环境
FROM php:8.2-fpm-alpine AS runtime
# 复制构建产物
COPY --from=builder /app/vendor /var/www/html/vendor
COPY . /var/www/html
# 安装生产所需扩展
RUN docker-php-ext-install pdo_mysql opcache
# 优化配置
COPY docker/php.ini /usr/local/etc/php/conf.d/custom.ini
COPY docker/www.conf /usr/local/etc/php-fpm.d/www.conf
# 设置权限
RUN chown -R www-data:www-data /var/www/html/storage /var/www/html/bootstrap/cache
EXPOSE 9000
CMD ["php-fpm"]

优势：

最终镜像仅270MB（相比单阶段550MB）
不包含composer、git等工具
利用层缓存加速构建（依赖层变化频率远低于代码层）

常用扩展与配置实战

1 常见PHP扩展安装表

扩展	安装命令	适用框架
pdo_mysql	`docker-php-ext-install pdo_mysql`	多数项目
redis	`pecl install redis && docker-php-ext-enable redis`	缓存场景
imagick	`apk add --no-cache imagemagick-dev && pecl install imagick`	图片处理
sockets	`docker-php-ext-install sockets`	WebSocket

2 性能优化配置示例

; docker/php.ini
opcache.enable=1
opcache.memory_consumption=128
opcache.max_accelerated_files=10000
opcache.revalidate_freq=0
memory_limit=256M
max_execution_time=30
upload_max_filesize=20M

性能与安全最佳实践

1 镜像层缓存技巧

先复制composer.json和composer.lock（依赖不常变）
再运行composer install
最后复制其余代码（频繁变动的部分放在后面）

2 安全注意事项

禁用危险函数：在php.ini中添加disable_functions=exec,passthru,shell_exec,system
定期更新基础镜像：docker pull php:8.2-fpm-alpine（每月一次）
使用非root用户运行PHP-FPM（参考第3节）
限制容器资源：在docker run时添加--memory=512m --cpus=0.5

3 CI/CD集成建议

在Dockerfile末尾添加健康检查：

HEALTHCHECK --interval=30s --timeout=3s \
  CMD curl -f http://localhost:9000/ping || exit 1

常见问题问答（FAQ）

Q1：为什么我的PHP容器无法连接MySQL？
A：通常因缺少pdo_mysql扩展，检查Dockerfile中是否包含docker-php-ext-install pdo_mysql,确认后重建镜像。

Q2：多阶段构建时，如何确保.env文件不被复制到镜像？
A：使用.dockerignore文件：

.env
.git
node_modules/
tests/

Q3：安装扩展时出现“lib not found”错误怎么办？
A：以GD库为例，需先安装系统库：apk add --no-cache libpng-dev freetype-dev，再执行docker-php-ext-install gd，类似问题可参考官方扩展列表。

Q4：容器启动后报错“permission denied”如何解决？
A：检查STORAGE目录权限，在Dockerfile中添加：

RUN chmod -R 775 /var/www/html/storage

Q5：生产环境应该用Apache还是Nginx？
A：建议使用Nginx+PHP-FPM组合，示例生产部署命令：

docker run -d --name php-app \
  --network my-network \
  -v ./storage:/var/www/html/storage \
  my-php-image:latest

Nginx容器通过fastcgi_pass php-app:9000连接。

通过以上步骤，您可以从零构建一个高效、安全且易于维护的PHP Docker镜像，生产级Dockerfile的核心在于多阶段构建减少体积、使用官方脚本标准化扩展安装以及非root用户运行容器,开始实践吧！