docker-php-dev 镜像文档

概述

docker-php-dev 是 WP STAGING 的专用开发环境 Docker 镜像，基于 PHP 7.4 构建，提供 CLI 和 PHP-FPM 两种运行模式。镜像包含两个版本：php:7.4 内置 xDebug 调试工具，适用于开发调试场景；php:7.4-ci 功能与 php:7.4 一致，但移除了 xDebug，可用于无需调试的构建或测试环节。

镜像源码地址：[***]

核心功能与特性

• PHP 版本：基于官方 PHP 7.4 镜像构建，兼容性稳定。
• 运行模式：同时支持 CLI（命令行接口）和 PHP-FPM（FastCGI 进程管理器），满足不同开发需求。
• 调试支持：php:7.4 版本内置 xDebug 扩展，可直接用于代码调试。
• 轻量版本：php:7.4-ci 版本移除 xDebug，减少镜像体积，提升运行效率，适用于 CI/CD 流程。

使用场景

• WP STAGING 项目开发：作为本地开发环境，提供 PHP 7.4 运行时及调试能力。
• 代码调试：通过 php:7.4 版本的 xDebug 扩展，配合 IDE 实现断点调试、性能分析等。
• CI/CD 流程：在持续集成/部署环节，使用 php:7.4-ci 版本执行代码检查、单元测试等无需调试的任务。
• PHP 7.4 环境验证：快速搭建 PHP 7.4 环境，验证应用兼容性。

使用方法

1. 拉取镜像

从 Docker Hub 拉取指定版本镜像：

# 拉取带 xDebug 的开发版本
docker pull wpstaging/php:7.4

# 拉取不含 xDebug 的轻量版本
docker pull wpstaging/php:7.4-ci

2. 运行容器

CLI 模式示例

执行 PHP 命令行脚本（如查看 PHP 版本）：

# 使用带 xDebug 的版本
docker run --rm wpstaging/php:7.4 php -v

# 使用轻量版本
docker run --rm wpstaging/php:7.4-ci php -v

PHP-FPM 模式示例

启动 PHP-FPM 服务并映射端口（默认监听 9000 端口）：

# 启动 FPM 服务（带 xDebug）
docker run -d --name php-fpm-dev -p 9000:9000 wpstaging/php:7.4

# 启动 FPM 服务（轻量版）
docker run -d --name php-fpm-ci -p 9000:9000 wpstaging/php:7.4-ci

挂载项目目录

将本地项目目录挂载到容器中，运行项目代码：

# 挂载当前目录到容器 /app，执行脚本
docker run --rm -v $(pwd):/app wpstaging/php:7.4 php /app/index.php

3. xDebug 配置（仅 php:7.4 版本）

默认已启用 xDebug，可通过环境变量或挂载配置文件自定义调试参数（如远程主机、端口等）。示例：

# 自定义 xDebug 远程主机（IDE 所在主机 IP）
docker run --rm -e XDEBUG_CONFIG="remote_host=192.168.1.100" wpstaging/php:7.4 php /app/debug.php

Docker Compose 示例

以下是配合 Nginx 使用 PHP-FPM 的 docker-compose.yml 示例（使用带 xDebug 的版本）：

version: '3'
services:
  php-fpm:
    image: wpstaging/php:7.4
    volumes:
      - ./project:/var/www/html
    environment:
      - XDEBUG_CONFIG=remote_host=host.docker.internal  # 适用于 Docker Desktop（Windows/Mac）
    ports:
      - "9000:9000"
  
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./project:/var/www/html
      - ./nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - php-fpm