如何将PHP项目打包成镜像部署？

wen PHP项目 2026-06-17 2

本文目录导读：

如何将PHP项目打包成镜像部署？

目录导读
为什么需要将PHP项目打包成镜像？
准备工作：环境与项目结构梳理
第一步：编写Dockerfile（核心步骤）
第二步：构建镜像与优化体积
第三步：通过docker-compose整合服务
第四步：推送镜像到仓库与部署
常见问题FAQ
结语与最佳实践建议

PHP项目Docker镜像打包与部署完整指南

目录导读

为什么需要将PHP项目打包成镜像？
准备工作：环境与项目结构梳理
第一步：编写Dockerfile（核心步骤）
- 基础镜像选择（Alpine vs Debian）
- 安装PHP扩展与Composer依赖
- 复制项目代码与设置权限
第二步：构建镜像与优化体积
- 多阶段构建实战
- 利用.dockerignore排除无用文件
第三步：通过docker-compose整合服务
- 联动Nginx、MySQL、Redis容器
- 环境变量管理与配置文件挂载
第四步：推送镜像到仓库与部署
- 私有仓库（Harbor/Nexus） vs 公有云
- 服务器上拉取并启动容器
常见问题FAQ
结语与最佳实践建议

为什么需要将PHP项目打包成镜像？

在传统LAMP/LEMP环境中，PHP项目部署常面临“环境不一致”的噩梦——本地运行正常，测试服务器报错扩展缺失，生产环境又出现路径问题，而通过Docker镜像，你可以将应用代码 + PHP版本 + 扩展 + 系统依赖完整打包，实现一次构建,四处运行。

核心优势：

环境一致性：镜像内包含所有运行时依赖，消除“我电脑上能跑”的窘境。
快速伸缩：配合Kubernetes或Swarm，秒级扩容/回滚。
版本控制：每个镜像对应一个不可变的版本，CI/CD流畅通。

准备工作：环境与项目结构梳理

在开始前，请确保你的服务器/开发机已安装：

Docker 20.10+
Git（用于拉取项目代码）

典型PHP项目目录示例（以Laravel为例）：

my-php-app/
├── app/
├── bootstrap/
├── config/
├── database/
├── public/
├── resources/
├── routes/
├── storage/
├── vendor/       # Composer依赖（编译后生成）
├── .env.example
├── composer.json
├── Dockerfile    # 待创建
└── docker-compose.yml  # 待创建

注意：vendor目录通常不纳入Git,但会在构建时通过Composer自动安装。

第一步：编写Dockerfile（核心步骤）

基础镜像选择：Alpine vs Debian

Alpine（推荐）：体积小（约5MB基础），安全性高，但部分扩展需额外编译（如GD库扩展）。
Debian/Ubuntu：兼容性好，适合需要大量系统库的项目（如PDF生成、图像处理）。

# 以官方PHP 8.2 FPM Alpine为例
FROM php:8.2-fpm-alpine AS base
# 安装系统依赖（Alpine使用apk）
RUN apk add --no-cache \
    git \
    unzip \
    libpng-dev \
    libjpeg-turbo-dev \
    freetype-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install pdo_mysql bcmath gd
# 安装Composer（官方推荐镜像方式）
COPY --from=composer:2.7 /usr/bin/composer /usr/bin/composer
# 设置工作目录
WORKDIR /var/www/html
# 先复制composer文件（利用缓存）
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader
# 复制项目剩余文件
COPY . .
# 设置权限（PHP-FPM默认用户www-data）
RUN chown -R www-data:www-data storage bootstrap/cache

关键点：

先复制composer.json再运行composer install，可充分利用Docker缓存层。
docker-php-ext-install是官方提供的便捷脚本,无需手动配置编译参数。

常见扩展安装示例

RUN docker-php-ext-install pdo_mysql opcache redis
# 非官方扩展需额外pecl安装
RUN pecl install xdebug-3.3.0 && docker-php-ext-enable xdebug

第二步：构建镜像与优化体积

多阶段构建实战

当镜像包含编译工具（如gcc）、开发依赖时，会产生大量无用文件，利用多阶段构建可分离“编译环境”和“运行环境”。

# 第一阶段：构建依赖
FROM composer:2.7 AS vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --optimize-autoloader --no-interaction
# 第二阶段：运行镜像
FROM php:8.2-fpm-alpine
WORKDIR /var/www/html
COPY --from=vendor /app/vendor ./vendor
COPY . .
# ...其他配置

体积对比： 单阶段镜像约250MB,多阶段后可压缩至120MB左右。

.dockerignore文件

在项目根目录创建.dockerignore,避免将无关文件打包进镜像：

.git
.env
node_modules/
tests/
storage/framework/cache/data/*
storage/logs/*

第三步：通过docker-compose整合服务

实际生产环境需要Nginx、MySQL、Redis等服务联动，以下是完整的docker-compose.yml示例：

version: '3.8'
services:
  app:
    build: .
    container_name: php_app
    volumes:
      - ./public:/var/www/html/public   # 挂载静态文件（可选）
      - ./storage:/var/www/html/storage  # 持久化日志/缓存
    environment:
      - DB_HOST=mysql
      - DB_DATABASE=myapp
      - DB_USERNAME=root
      - DB_PASSWORD=secret
    depends_on:
      - mysql
      - redis
    networks:
      - internal
  nginx:
    image: nginx:1.25-alpine
    container_name: php_nginx
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
      - ./public:/var/www/html/public
    depends_on:
      - app
    networks:
      - internal
  mysql:
    image: mysql:8.0
    container_name: php_mysql
    environment:
      - MYSQL_ROOT_PASSWORD=secret
      - MYSQL_DATABASE=myapp
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - internal
  redis:
    image: redis:7-alpine
    container_name: php_redis
    volumes:
      - redis_data:/data
    networks:
      - internal
volumes:
  mysql_data:
  redis_data:
networks:
  internal:
    driver: bridge

使用方式：
docker-compose up -d --build 一键构建并启动所有服务。

第四步：推送镜像到仓库与部署

推送镜像

# 登录到镜像仓库（以Docker Hub为例）
docker login -u your_docker_id -p your_password
# 标记镜像
docker tag php-app:latest your_docker_id/php-app:v1.0
# 推送
docker push your_docker_id/php-app:v1.0

若使用私有仓库（如Harbor）：docker push your_harbor_domain:8080/library/php-app:v1.0

服务器拉取并启动

# 拉取镜像
docker pull your_docker_id/php-app:v1.0
# 运行容器
docker run -d --name my_app \
  -p 8080:80 \
  -e DB_HOST=192.168.x.x \
  -e DB_PASSWORD=securepassword \
  your_docker_id/php-app:v1.0

生产建议：