PHP容器化部署是目前主流的项目部署方式，通过Docker可以将PHP运行环境和项目代码打包成标准化镜像，避免不同环境带来的依赖差异问题。实际部署过程中可能会遇到各种报错，需要结合具体场景排查解决。
PHP容器化部署基础准备
在开始部署前，需要确保本地已经安装好Docker环境，并且准备好待部署的PHP项目代码。如果是首次使用Docker，可以先执行以下命令验证Docker是否正常运行：
docker --version docker ps
如果命令能正常返回版本信息和容器列表，说明Docker环境已经就绪。
Dockerfile编写规范
Dockerfile是构建PHP镜像的核心文件，需要根据项目需求选择合适的PHP基础镜像，安装必要的扩展和依赖。以下是一个通用的PHP Dockerfile示例，适用于大多数PHP Web项目：
# 选择官方PHP 8.2 FPM基础镜像
FROM php:8.2-fpm
# 设置工作目录
WORKDIR /var/www/html
# 安装系统依赖和PHP扩展
RUN apt-get update && apt-get install -y
libonig-dev
libzip-dev
unzip
&& docker-php-ext-install pdo_mysql mysqli zip mbstring opcache
&& apt-get clean && rm -rf /var/lib/apt/lists/*
# 安装Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
# 复制项目代码到工作目录
COPY . .
# 安装项目依赖
RUN composer install --no-dev --optimize-autoloader
# 暴露9000端口（PHP FPM默认端口）
EXPOSE 9000
# 启动PHP FPM服务
CMD ["php-fpm"]
编写Dockerfile时需要注意：基础镜像的版本要和项目兼容，扩展安装要根据项目实际需求调整，避免安装不必要的组件增加镜像体积。
镜像构建与容器启动
编写完成Dockerfile后，在项目根目录执行以下命令构建镜像：
docker build -t php-app:latest .
镜像构建完成后，可以通过以下命令启动容器：
docker run -d -p 9000:9000 --name php-container php-app:latest
如果需要和Nginx等Web服务器配合使用，可以通过Docker网络将两者关联，让Nginx可以转发请求到PHP容器的9000端口。
常见部署报错与解决方法
报错1：镜像构建时扩展安装失败
这类报错通常是因为缺少系统依赖，比如安装pdo_mysql扩展时如果没有对应的lib库就会失败。解决方法是在安装扩展前先安装对应的系统依赖，参考上述Dockerfile中的依赖安装步骤即可。
报错2：容器启动后立即退出
可以通过docker logs 容器ID查看容器日志，常见原因是PHP FPM配置错误或者项目代码有语法错误。如果是配置问题，可以修改php-fpm.conf后重新构建镜像；如果是代码问题，修复代码后重新构建即可。
报错3：端口冲突报错
报错信息通常会提示端口已经被占用，可以执行netstat -tuln | grep 端口号查看占用端口的进程，停止对应进程后更换映射端口，或者修改容器映射的宿主机端口重新启动容器。
报错4：项目依赖安装失败
通常是Composer镜像源访问慢或者依赖版本不兼容，可以在Dockerfile中配置Composer国内镜像源，修改安装依赖的步骤为：
RUN composer config -g repos.packagist composer https://mirrors.ipipp.com/composer/
&& composer install --no-dev --optimize-autoloader
部署验证
容器启动后，可以执行以下命令进入容器内部验证PHP环境是否正常：
docker exec -it php-container bash php -v php -m
如果能正常返回PHP版本和已安装的扩展列表，说明PHP环境运行正常，再结合Web服务器验证项目是否可以正常访问即可。
PHPDockerDockerfile容器化部署修改时间：2026-06-22 14:54:34