WordPress本地开发环境PHP镜像文档

1. 镜像概述和主要用途

本镜像是专为WordPress本地开发环境设计的PHP运行时环境，基于官方PHP镜像构建并针对WordPress开发需求优化。其核心用途是为开发者提供与WordPress官方推荐环境兼容的本地PHP运行环境，支持快速搭建、配置灵活，可无缝集成MySQL、Nginx等服务，降低本地开发环境搭建门槛。

2. 核心功能和特性

• 多PHP版本支持：提供PHP 7.4、8.0、8.1、8.2等主流版本标签，适配不同WordPress版本兼容性要求。
• 预装WordPress必要扩展：默认集成mysqli、gd、curl、mbstring、zip、exif、imagick等WordPress核心依赖扩展。
• 开发工具集成：内置Xdebug调试工具，支持断点调试、性能分析，满足开发调试需求。
• 灵活配置：支持通过环境变量或挂载配置文件自定义PHP.ini参数，如内存限制、上传大小等。
• 轻量优化：基于Alpine或Debian slim基础镜像构建，体积较小，启动速度快。
• 兼容性设计：与Docker Compose无缝集成，可快速组合MySQL、Nginx等服务形成完整开发栈。

3. 使用场景和适用范围

适用场景

• WordPress主题开发与调试
• WordPress插件功能开发与测试
• WordPress站点迁移或版本升级前的本地验证
• 多版本PHP环境切换测试（如验证插件在不同PHP版本下的兼容性）

适用范围

• 仅限本地开发环境，不建议用于生产环境部署
• 个人开发者、开发团队本地开发工作流
• 需快速复现线上环境问题的调试场景

4. 使用方法和配置说明

4.1 获取镜像

从Docker Hub拉取指定PHP版本的镜像（以PHP 8.1为例）：

docker pull [镜像仓库地址]/wordpress-dev-php:8.1  # 替换为实际镜像仓库地址

镜像标签说明：

• 8.1：PHP 8.1版本（默认标签，包含常用扩展）
• 8.1-xdebug：PHP 8.1版本，预装Xdebug扩展
• 7.4：PHP 7.4版本（兼容旧版WordPress）

4.2 基本使用（docker run）

通过docker run命令快速启动PHP环境，挂载本地WordPress代码目录：

docker run -d \
  --name wp-dev-php \
  -p 9000:9000 \  # PHP-FPM端口（如需配合Nginx使用）
  -v /本地/wordpress代码目录:/var/www/html \  # 挂载本地WordPress代码
  -e PHP_MEMORY_LIMIT=512M \  # 自定义PHP内存限制
  -e PHP_UPLOAD_MAX_FILESIZE=64M \  # 自定义上传文件大小限制
  [镜像仓库地址]/wordpress-dev-php:8.1

4.3 Docker Compose集成（推荐）

通过Docker Compose组合PHP、MySQL、Nginx服务，形成完整开发环境。创建docker-compose.yml文件：

version: '3.8'

services:
  php:
    image: [镜像仓库地址]/wordpress-dev-php:8.1-xdebug
    volumes:
      - ./wordpress:/var/www/html  # 本地WordPress代码目录
      - ./php.ini:/usr/local/etc/php/conf.d/custom.ini  # 挂载自定义PHP配置
    environment:
      - PHP_MEMORY_LIMIT=512M
      - XDEBUG_MODE=debug  # 启用Xdebug调试模式
      - XDEBUG_CLIENT_HOST=host.docker.internal  # 本地IDE地址（Windows/macOS）
      - XDEBUG_CLIENT_PORT=9003  # Xdebug监听端口（需与IDE配置一致）
      - WORDPRESS_DB_HOST=db:3306  # 数据库服务地址（关联下方db服务）
    depends_on:
      - db

  db:
    image: mysql:8.0
    volumes:
      - db_data:/var/lib/mysql
    environment:
      - MYSQL_ROOT_PASSWORD=rootpass
      - MYSQL_DATABASE=wordpress
      - MYSQL_USER=wpuser
      - MYSQL_PASSWORD=wppass

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./wordpress:/var/www/html
      - ./nginx.conf:/etc/nginx/conf.d/default.conf  # Nginx配置（需指向PHP-FPM）
    depends_on:
      - php

volumes:
  db_data:

启动服务：

docker-compose up -d

5. 环境变量说明

6. 扩展管理和自定义配置

6.1 自定义PHP.ini配置

方法1：通过环境变量

直接通过-e参数传递PHP.ini参数（仅支持部分常用参数，见环境变量说明）。

方法2：挂载配置文件

创建本地custom.ini文件，添加自定义配置：

; custom.ini
display_errors = On
error_reporting = E_ALL
max_input_vars = 5000

挂载到容器的PHP配置扫描目录：

-v /本地/custom.ini:/usr/local/etc/php/conf.d/custom.ini

6.2 Xdebug配置（仅xdebug标签镜像）

如需远程调试（如配合VS Code、PHPStorm），需确保：

1. 镜像标签包含-xdebug（如8.1-xdebug）
2. 环境变量XDEBUG_MODE=debug
3. XDEBUG_CLIENT_HOST指向本地IDE所在IP（Windows/macOS可直接使用host.docker.internal，Linux需手动指定宿主机IP）

PHPStorm配置示例：

• 调试端口：9003（与XDEBUG_CLIENT_PORT一致）
• 服务器映射：本地/本地/wordpress代码目录映射到容器/var/www/html

7. 注意事项

1. 安全提示：本地开发环境可关闭部分安全限制（如display_errors=On），但需避免将包含敏感配置的镜像提交到公开仓库。
2. 性能优化：本地开发时可启用PHP OPcache加速代码加载（通过opcache.enable=On配置）。
3. 版本兼容性：选择PHP版本时需参考目标WordPress版本的官方兼容性文档（如WordPress 6.0+推荐PHP 7.4+）。
4. 数据持久化：通过挂载卷（Volume）确保代码和数据库数据在容器重启后不丢失（如docker-compose.yml中的db_data卷）。
5. 端口冲突：启动前确保宿主机端口（如9000、80）未被占用，可通过docker ps检查已运行容器。