1. Docker部署PHP项目概述在当今的Web开发领域Docker已经成为部署PHP项目的标准工具之一。作为一名长期使用Docker部署PHP应用的开发者我发现这种容器化部署方式能完美解决在我机器上能跑的经典问题。通过Docker我们可以将PHP运行环境、Web服务器如Nginx、数据库如MySQL等组件打包成独立的容器实现开发、测试和生产环境的高度一致性。PHP 8.0已经成为现代PHP应用的最低版本要求但很多服务器上仍然运行着PHP 7.4甚至更老的版本。使用Docker可以轻松解决这种版本冲突问题让你无需修改服务器配置就能运行最新PHP版本的应用。我在实际项目中就遇到过这样的情况客户服务器运行的是PHP 7.4.33而我们的Laravel项目需要PHP 8.1通过Docker部署完美避开了这个矛盾。2. 环境准备与工具选型2.1 Docker安装与配置在开始之前你需要确保系统已经安装了Docker和Docker Compose。对于Windows和Mac用户推荐直接安装Docker Desktop它提供了图形界面和命令行工具的一体化体验。Linux用户可以通过以下命令安装# Ubuntu/Debian sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后建议将当前用户加入docker组以避免频繁使用sudosudo usermod -aG docker $USER newgrp docker # 立即生效注意如果在Windows上遇到Docker Desktop failed to start because virtualisation support wasnt detected错误需要进入BIOS启用虚拟化支持VT-x/AMD-V。2.2 项目结构规划合理的项目结构能大幅提升后续维护效率。我通常采用以下目录结构my-php-project/ ├── docker/ │ ├── php/ │ │ └── Dockerfile # PHP容器配置 │ └── nginx/ │ └── default.conf # Nginx配置 ├── src/ # PHP源代码 ├── docker-compose.yml # 容器编排 └── .env # 环境变量这种结构将Docker相关配置集中管理同时保持应用代码的独立性。对于复杂的项目你还可以进一步细分比如为不同服务创建单独的配置目录。3. Docker容器配置详解3.1 PHP容器配置创建docker/php/Dockerfile文件这是构建PHP环境的核心。以下是一个支持PHP 8.2的配置示例FROM php:8.2-fpm # 安装系统依赖 RUN apt-get update apt-get install -y \ libzip-dev \ libpng-dev \ libjpeg-dev \ libfreetype6-dev \ libssl-dev \ libxml2-dev \ docker-php-ext-configure gd --with-freetype --with-jpeg \ docker-php-ext-install -j$(nproc) gd pdo_mysql zip opcache exif pcntl # 安装Composer RUN curl -sS https://getcomposer.org/installer | php -- --install-dir/usr/local/bin --filenamecomposer # 设置工作目录 WORKDIR /var/www/html # 复制PHP配置文件 COPY ./docker/php/php.ini /usr/local/etc/php/conf.d/custom.ini这个配置做了几件重要的事情基于官方PHP 8.2 FPM镜像构建安装了常见的PHP扩展GD、PDO_MySQL、Zip等配置了Composer作为全局工具允许通过自定义php.ini覆盖默认配置实操心得如果你需要安装特定的PHP扩展可以使用docker-php-ext-install命令。对于PECL扩展先用pecl install安装然后用docker-php-ext-enable启用。3.2 Nginx配置创建docker/nginx/default.conf文件配置Web服务器server { listen 80; server_name localhost; root /var/www/html/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass php:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location ~ /\.ht { deny all; } }这个配置实现了将请求路由到PHP-FPM处理支持Laravel等框架的URL重写禁止访问.htaccess文件安全性考虑4. Docker Compose编排服务4.1 基础服务编排创建docker-compose.yml文件定义整个应用栈version: 3.8 services: php: build: context: . dockerfile: docker/php/Dockerfile volumes: - ./src:/var/www/html environment: - APP_ENVlocal depends_on: - mysql - redis nginx: image: nginx:alpine ports: - 8080:80 volumes: - ./src:/var/www/html - ./docker/nginx:/etc/nginx/conf.d depends_on: - php mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: secret MYSQL_DATABASE: app_db MYSQL_USER: app_user MYSQL_PASSWORD: password volumes: - mysql_data:/var/lib/mysql redis: image: redis:alpine ports: - 6379:6379 volumes: - redis_data:/data volumes: mysql_data: redis_data:这个配置定义了四个服务PHP-FPM服务基于我们自定义的DockerfileNginx Web服务器MySQL数据库Redis缓存服务4.2 环境变量管理使用.env文件管理敏感配置和可变参数# PHP配置 APP_ENVlocal APP_DEBUGtrue # 数据库配置 DB_HOSTmysql DB_PORT3306 DB_DATABASEapp_db DB_USERNAMEapp_user DB_PASSWORDpassword # Redis配置 REDIS_HOSTredis REDIS_PORT6379然后在docker-compose.yml中引用这些变量environment: - APP_ENV${APP_ENV} - DB_HOST${DB_HOST}重要提示永远不要将.env文件提交到版本控制系统。确保它在.gitignore中。5. 项目部署与调试5.1 构建并启动容器运行以下命令构建和启动所有服务docker-compose up -d --build这个命令会构建自定义PHP镜像拉取其他服务的官方镜像创建并启动所有容器启动后你的应用将在http://localhost:8080可用。5.2 常见问题排查问题1PHP版本不兼容错误信息PHP version must be greater than 8.0, current version: 7.4.33解决方案确保Dockerfile中指定的基础镜像版本正确如FROM php:8.2-fpm问题2扩展缺失错误信息Class Redis not found解决方案在Dockerfile中添加扩展安装命令RUN pecl install redis docker-php-ext-enable redis问题3权限问题错误信息Failed to open stream: Permission denied解决方案确保容器内外的文件权限一致。可以在Dockerfile中添加RUN chown -R www-data:www-data /var/www/html问题4数据库连接失败错误信息SQLSTATE[HY000] [2002] Connection refused解决方案检查MySQL服务是否启动确认环境变量中的数据库主机名与compose服务名一致确保应用配置使用了正确的环境变量6. 高级配置与优化6.1 多阶段构建优化对于生产环境可以使用多阶段构建减小镜像体积# 构建阶段 FROM composer:2 as builder WORKDIR /app COPY . . RUN composer install --no-dev --optimize-autoloader # 生产阶段 FROM php:8.2-fpm-alpine COPY --frombuilder /app /var/www/html COPY docker/php/php.ini /usr/local/etc/php/conf.d/custom.ini RUN docker-php-ext-install pdo_mysql opcache这种构建方式将开发依赖如Composer排除在最终镜像外显著减小了镜像大小。6.2 PHP性能调优在docker/php/php.ini中添加以下优化配置; OPcache配置 opcache.enable1 opcache.memory_consumption128 opcache.max_accelerated_files10000 opcache.validate_timestamps0 ; 生产环境设为0开发环境设为1 ; 内存限制 memory_limit256M ; 执行时间 max_execution_time30 ; 上传限制 upload_max_filesize20M post_max_size22M6.3 日志与监控配置日志收集有助于问题排查services: php: logging: driver: json-file options: max-size: 10m max-file: 3对于生产环境可以考虑添加Prometheus和Grafana进行监控。7. 实际项目中的经验分享在多年的Docker化PHP项目部署实践中我总结了以下几点关键经验版本锁定在docker-compose.yml中固定镜像版本如php:8.2-fpm而不是php:latest避免因自动更新导致的不兼容问题。数据持久化对于数据库等重要数据一定要使用volumes持久化存储。我曾经因为忘记配置volume导致测试数据全部丢失。开发效率优化在开发环境中可以启用Xdebug进行远程调试RUN pecl install xdebug docker-php-ext-enable xdebug COPY docker/php/xdebug.ini /usr/local/etc/php/conf.d/xdebug.iniCI/CD集成将Docker构建过程集成到CI/CD流水线中。例如在GitHub Actions中可以这样配置jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - run: docker-compose up -d --build - run: docker-compose exec php phpunit本地开发技巧使用docker-compose exec php bash进入PHP容器执行命令保持环境一致性。比如运行Artisan命令docker-compose exec php php artisan migrate多环境配置通过不同的compose文件支持多环境。例如docker-compose.yml基础服务定义docker-compose.dev.yml开发环境覆盖配置如Xdebugdocker-compose.prod.yml生产环境配置如SSL证书启动时指定文件docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d 
长河君 · 2026/10/31 15:59:41 · 阅读 1.2k Docker部署PHP项目全攻略：从环境配置到生产优化
1. Docker部署PHP项目概述在当今的Web开发领域Docker已经成为部署PHP项目的标准工具之一。作为一名长期使用Docker部署PHP应用的开发者我发现这种容器化部署方式能完美解决在我机器上能跑的经典问题。通过Docker我们可以将PHP运行环境、Web服务器如Nginx、数据库如MySQL等组件打包成独立的容器实现开发、测试和生产环境的高度一致性。PHP 8.0已经成为现代PHP应用的最低版本要求但很多服务器上仍然运行着PHP 7.4甚至更老的版本。使用Docker可以轻松解决这种版本冲突问题让你无需修改服务器配置就能运行最新PHP版本的应用。我在实际项目中就遇到过这样的情况客户服务器运行的是PHP 7.4.33而我们的Laravel项目需要PHP 8.1通过Docker部署完美避开了这个矛盾。2. 环境准备与工具选型2.1 Docker安装与配置在开始之前你需要确保系统已经安装了Docker和Docker Compose。对于Windows和Mac用户推荐直接安装Docker Desktop它提供了图形界面和命令行工具的一体化体验。Linux用户可以通过以下命令安装# Ubuntu/Debian sudo apt-get update sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin安装完成后建议将当前用户加入docker组以避免频繁使用sudosudo usermod -aG docker $USER newgrp docker # 立即生效注意如果在Windows上遇到Docker Desktop failed to start because virtualisation support wasnt detected错误需要进入BIOS启用虚拟化支持VT-x/AMD-V。2.2 项目结构规划合理的项目结构能大幅提升后续维护效率。我通常采用以下目录结构my-php-project/ ├── docker/ │ ├── php/ │ │ └── Dockerfile # PHP容器配置 │ └── nginx/ │ └── default.conf # Nginx配置 ├── src/ # PHP源代码 ├── docker-compose.yml # 容器编排 └── .env # 环境变量这种结构将Docker相关配置集中管理同时保持应用代码的独立性。对于复杂的项目你还可以进一步细分比如为不同服务创建单独的配置目录。3. Docker容器配置详解3.1 PHP容器配置创建docker/php/Dockerfile文件这是构建PHP环境的核心。以下是一个支持PHP 8.2的配置示例FROM php:8.2-fpm # 安装系统依赖 RUN apt-get update apt-get install -y \ libzip-dev \ libpng-dev \ libjpeg-dev \ libfreetype6-dev \ libssl-dev \ libxml2-dev \ docker-php-ext-configure gd --with-freetype --with-jpeg \ docker-php-ext-install -j$(nproc) gd pdo_mysql zip opcache exif pcntl # 安装Composer RUN curl -sS https://getcomposer.org/installer | php -- --install-dir/usr/local/bin --filenamecomposer # 设置工作目录 WORKDIR /var/www/html # 复制PHP配置文件 COPY ./docker/php/php.ini /usr/local/etc/php/conf.d/custom.ini这个配置做了几件重要的事情基于官方PHP 8.2 FPM镜像构建安装了常见的PHP扩展GD、PDO_MySQL、Zip等配置了Composer作为全局工具允许通过自定义php.ini覆盖默认配置实操心得如果你需要安装特定的PHP扩展可以使用docker-php-ext-install命令。对于PECL扩展先用pecl install安装然后用docker-php-ext-enable启用。3.2 Nginx配置创建docker/nginx/default.conf文件配置Web服务器server { listen 80; server_name localhost; root /var/www/html/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ \.php$ { fastcgi_pass php:9000; fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location ~ /\.ht { deny all; } }这个配置实现了将请求路由到PHP-FPM处理支持Laravel等框架的URL重写禁止访问.htaccess文件安全性考虑4. Docker Compose编排服务4.1 基础服务编排创建docker-compose.yml文件定义整个应用栈version: 3.8 services: php: build: context: . dockerfile: docker/php/Dockerfile volumes: - ./src:/var/www/html environment: - APP_ENVlocal depends_on: - mysql - redis nginx: image: nginx:alpine ports: - 8080:80 volumes: - ./src:/var/www/html - ./docker/nginx:/etc/nginx/conf.d depends_on: - php mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: secret MYSQL_DATABASE: app_db MYSQL_USER: app_user MYSQL_PASSWORD: password volumes: - mysql_data:/var/lib/mysql redis: image: redis:alpine ports: - 6379:6379 volumes: - redis_data:/data volumes: mysql_data: redis_data:这个配置定义了四个服务PHP-FPM服务基于我们自定义的DockerfileNginx Web服务器MySQL数据库Redis缓存服务4.2 环境变量管理使用.env文件管理敏感配置和可变参数# PHP配置 APP_ENVlocal APP_DEBUGtrue # 数据库配置 DB_HOSTmysql DB_PORT3306 DB_DATABASEapp_db DB_USERNAMEapp_user DB_PASSWORDpassword # Redis配置 REDIS_HOSTredis REDIS_PORT6379然后在docker-compose.yml中引用这些变量environment: - APP_ENV${APP_ENV} - DB_HOST${DB_HOST}重要提示永远不要将.env文件提交到版本控制系统。确保它在.gitignore中。5. 项目部署与调试5.1 构建并启动容器运行以下命令构建和启动所有服务docker-compose up -d --build这个命令会构建自定义PHP镜像拉取其他服务的官方镜像创建并启动所有容器启动后你的应用将在http://localhost:8080可用。5.2 常见问题排查问题1PHP版本不兼容错误信息PHP version must be greater than 8.0, current version: 7.4.33解决方案确保Dockerfile中指定的基础镜像版本正确如FROM php:8.2-fpm问题2扩展缺失错误信息Class Redis not found解决方案在Dockerfile中添加扩展安装命令RUN pecl install redis docker-php-ext-enable redis问题3权限问题错误信息Failed to open stream: Permission denied解决方案确保容器内外的文件权限一致。可以在Dockerfile中添加RUN chown -R www-data:www-data /var/www/html问题4数据库连接失败错误信息SQLSTATE[HY000] [2002] Connection refused解决方案检查MySQL服务是否启动确认环境变量中的数据库主机名与compose服务名一致确保应用配置使用了正确的环境变量6. 高级配置与优化6.1 多阶段构建优化对于生产环境可以使用多阶段构建减小镜像体积# 构建阶段 FROM composer:2 as builder WORKDIR /app COPY . . RUN composer install --no-dev --optimize-autoloader # 生产阶段 FROM php:8.2-fpm-alpine COPY --frombuilder /app /var/www/html COPY docker/php/php.ini /usr/local/etc/php/conf.d/custom.ini RUN docker-php-ext-install pdo_mysql opcache这种构建方式将开发依赖如Composer排除在最终镜像外显著减小了镜像大小。6.2 PHP性能调优在docker/php/php.ini中添加以下优化配置; OPcache配置 opcache.enable1 opcache.memory_consumption128 opcache.max_accelerated_files10000 opcache.validate_timestamps0 ; 生产环境设为0开发环境设为1 ; 内存限制 memory_limit256M ; 执行时间 max_execution_time30 ; 上传限制 upload_max_filesize20M post_max_size22M6.3 日志与监控配置日志收集有助于问题排查services: php: logging: driver: json-file options: max-size: 10m max-file: 3对于生产环境可以考虑添加Prometheus和Grafana进行监控。7. 实际项目中的经验分享在多年的Docker化PHP项目部署实践中我总结了以下几点关键经验版本锁定在docker-compose.yml中固定镜像版本如php:8.2-fpm而不是php:latest避免因自动更新导致的不兼容问题。数据持久化对于数据库等重要数据一定要使用volumes持久化存储。我曾经因为忘记配置volume导致测试数据全部丢失。开发效率优化在开发环境中可以启用Xdebug进行远程调试RUN pecl install xdebug docker-php-ext-enable xdebug COPY docker/php/xdebug.ini /usr/local/etc/php/conf.d/xdebug.iniCI/CD集成将Docker构建过程集成到CI/CD流水线中。例如在GitHub Actions中可以这样配置jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv2 - run: docker-compose up -d --build - run: docker-compose exec php phpunit本地开发技巧使用docker-compose exec php bash进入PHP容器执行命令保持环境一致性。比如运行Artisan命令docker-compose exec php php artisan migrate多环境配置通过不同的compose文件支持多环境。例如docker-compose.yml基础服务定义docker-compose.dev.yml开发环境覆盖配置如Xdebugdocker-compose.prod.yml生产环境配置如SSL证书启动时指定文件docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d