PHP项目怎么迁移到Docker

wen PHP项目 2026-08-11 1

PHP项目容器化突围：从传统环境到Docker的无痛迁移实战指南

目录导读

为什么你的PHP项目需要Docker？ —— 环境一致性与CI/CD的痛点
迁移前的体检：盘点你的PHP项目依赖 —— 扩展、配置与文件权限
Docker化核心三件套 —— Dockerfile、docker-compose.yml与数据卷
经典坑位避雷指南 —— 文件上传、Session共享与定时任务
性能与安全调优 —— 镜像瘦身与容器内权限控制
问答环节 —— 高频疑问深度解析

为什么你的PHP项目需要Docker？

传统LAMP/LNMP环境中，90%的故障源于“在我机器上能跑”的魔咒，当团队加入新成员，或者需要模拟线上复杂配置（如Redis集群、图片裁剪库）时，手动配置环境通常耗时数小时甚至一整天，Docker通过镜像不可变性和编排文件声明式管理，将PHP运行环境、Nginx/Apache、扩展、Composer依赖完整打包，这意味着：

PHP项目怎么迁移到Docker

环境秒级复制：docker-compose up -d 一条命令拉起完整业务栈。
版本精准锁定：PHP 7.4 vs 8.1 共存互不干扰，旧项目无需升级即可维护。
资源隔离：将常驻内存的Worker进程与数据库分离部署，防止互相拖垮。

迁移前的体检：盘点你的PHP项目依赖

动手写Dockerfile之前,先执行以下“侦察兵动作”：

运行环境扫描：执行 php -m 导出当前已装扩展列表，特别关注 pdo_mysql、redis、gd、zip 等常用扩展，若用到 pcntl（常驻队列）或 swoole，需在Dockerfile中额外编译。
配置项梳理：检查 php.ini 中的 upload_max_filesize、memory_limit、session.save_path。建议通过环境变量注入，而非硬编码镜像中。
文件权限摸底：使用 ls -l 查看 storage、uploads 目录的属主和权限，迁移后容器内用户ID（UID）需与宿主机一致（如 useradd -u 1000）。
定时任务清单：列出Crontab条目，后续需放入独立容器或使用 docker exec 外部调用。

Docker化核心三件套

① Dockerfile（PHP-FPM镜像）

FROM php:8.2-fpm
# 安装系统依赖与PHP扩展
RUN apt-get update && apt-get install -y libzip-dev libmagickwand-dev \
    && docker-php-ext-install pdo_mysql zip opcache \
    && pecl install redis imagick \
    && docker-php-ext-enable redis imagick
# 复制项目代码（注意使用.dockerignore排除vendor与storage）
COPY . /var/www/html
# 专有用户运行，增强安全性
RUN useradd -u 1000 -m appuser && chown -R appuser:appuser /var/www/html
USER appuser

② docker-compose.yml（服务编排）

version: '3.8'
services:
  php:
    build: .
    volumes:
      - ./:/var/www/html
      - ./docker/php/uploads.ini:/usr/local/etc/php/conf.d/uploads.ini
    environment:
      - DB_HOST=database
      - REDIS_HOST=cache
  nginx:
    image: nginx:alpine
    ports: ["8080:80"]
    volumes:
      - ./:/var/www/html
      - ./docker/nginx.conf:/etc/nginx/conf.d/default.conf
  database:
    image: mysql:8.0
    env_file: .env.db
    volumes:
      - db_data:/var/lib/mysql
volumes:
  db_data:

③ 数据持久化策略

MySQL数据：使用命名卷 db_data。
用户上传文件：建议挂载宿主机目录（./storage），并避免写入容器层以防镜像体积膨胀与数据丢失。

经典坑位避雷指南

Session不同步：多容器负载时，默认Session存储在本地文件，解决方案：改用Redis存储（修改 session.save_handler）。
定时任务失效：Crontab在容器内默认不运行，推荐方案：创建独立 cron 容器，或宿主机cron执行 docker exec 命令。
文件权限崩溃：容器内用户与宿主机UID不一致时，上传文件会报“Permission denied”，务必在Dockerfile中 USER appuser，并将宿主机目录属主改为UID 1000。
Nginx配置陷阱：fastcgi_pass 需指向服务名（php:9000），而非 localhost。

性能与安全调优

镜像瘦身：使用 php:8.2-fpm-alpine 作为基础镜像，部署体积减少50%以上，但需注意部分PECL扩展编译依赖。
Opcache预加载：在容器启动命令中追加 -d opcache.enable-cli=1 和 -d opcache.validate_timestamps=0，提升性能。
只读根文件系统：在compose中配置 read_only: true，并将 storage、tmp 挂载为可写卷，防止恶意修改代码。
日志轮转：将Nginx与PHP错误日志输出到 stdout/stderr，由Docker日志驱动统一管理。

问答环节（高频疑问深度解析）

问1：旧项目使用Apache的 .htaccess 重写规则，迁移后如何处理？ 答：Docker推荐使用Nginx，手动改写规则至Nginx配置（约30分钟），若需保留Apache，可改用 php:8.2-apache 镜像并启用 mod_rewrite，但性能不如Nginx。

问2：迁移后线上图片无法显示，错误日志显示“Primary script unknown”？ 答：该问题90%源于Nginx配置中的 root 路径与PHP容器挂载路径不一致，确保两处都指向 /var/www/html/public（或项目入口目录），且 fastcgi_param SCRIPT_FILENAME 使用 $document_root$fastcgi_script_name。

问3：生产环境需要动态调整PHP扩展配置，能否在启动时覆盖？ 答：可以，在docker-compose中使用 command 覆盖默认启动命令，

command: php-fpm -d upload_max_filesize=100M -d memory_limit=512M

但仍建议在 conf.d/ 下管理自定义ini文件。

问4：如何实现代码热更新而不重建镜像？ 答：开发环境使用bind mount挂载项目代码（如compose中 - ./:/var/www/html），修改代码后立即生效，生产环境则需走CI/CD流水线重新构建镜像。

问5：容器内执行 composer install 非常慢，如何优化？ 答：使用多阶段构建，在构建阶段复制 composer.json 并执行 composer install，然后仅复制 vendor 目录到运行阶段，同时配置 COMPOSER_ALLOW_SUPERUSER=1 并添加国内镜像源。

通过上述步骤,传统PHP项目通常可在半天内完成Docker化迁移，关键在于线上环境的真实复刻与数据持久化设计，迁移后，你的团队将享受到“构建一次，到处运行”的极致快感，并且为后续Kubernetes集群编排打下坚实基础。