docker-xdebug 镜像文档

镜像概述和主要用途

docker-xdebug 是一个集成了 Xdebug 的 Docker 镜像，专为 GitLab CI、Drone CI、Dapper、GitHub Actions 等持续集成/持续部署（CI/CD）环境设计，用于 PHP 项目的调试、单元测试及代码覆盖率分析等测试场景。

镜像可从 Docker Hub 或 GitHub Container Registry 拉取。

核心功能和特性

• 多 PHP 版本支持：覆盖 PHP 5.5 至 8.0 等主流版本，满足不同项目的环境需求。
• 多变体支持：提供 CLI 和 Apache 两种基础镜像变体，适应不同部署场景。
• 预集成 Xdebug：已预装对应 PHP 版本兼容的 Xdebug 扩展，无需手动配置。
• CI/CD 兼容性：无缝适配 GitHub Actions、GitLab CI、Drone CI 等主流 CI 平台，简化测试流程。

使用场景和适用范围

适用场景

• PHP 项目在 CI/CD 流程中的代码调试。
• 单元测试、集成测试的执行与调试。
• 代码覆盖率报告生成（基于 Xdebug 的覆盖率分析功能）。

适用范围

• 支持的 CI 平台：GitHub Actions、GitLab CI、Drone CI、Dapper 等。
• 支持的 PHP 项目：基于 PHP 5.5 及以上版本开发的各类 PHP 应用。

支持的标签及对应 Dockerfile 链接

以下是当前支持的镜像标签及其对应的 Dockerfile 源文件链接：

版本与变体说明

PHP 版本与 Xdebug 版本对应关系

镜像变体说明

• 基础标签（如 8.0）：基于 PHP 官方 CLI 镜像构建，适用于命令行调试场景。
• -apache 标签（如 8.0-apache）：基于 PHP 官方 Apache 镜像构建，适用于需要 Web 服务器环境的调试场景。

使用方法和配置说明

1. 在 GitHub Actions 中使用

该镜像已发布至 GitHub Marketplace，可直接作为 Action 集成到工作流中：

- name: Xdebug Action
  uses: MilesChou/docker-xdebug@master

2. 直接通过 Docker 命令行使用

拉取镜像

# 拉取 PHP 8.0 CLI 版本
docker pull mileschou/xdebug:8.0

# 拉取 PHP 7.4 Apache 版本
docker pull mileschou/xdebug:7.4-apache

运行容器（CLI 场景示例）

挂载本地 PHP 项目目录，执行调试或测试命令：

docker run -it --rm \
  -v $(pwd):/app \
  -w /app \
  mileschou/xdebug:8.0 \
  php -dxdebug.mode=debug -dxdebug.client_host=host.docker.internal script.php

运行容器（Apache 场景示例）

启动 Apache 服务，通过宿主机端口访问调试：

docker run -d --rm \
  -p 8080:80 \
  -v $(pwd):/var/www/html \
  mileschou/xdebug:8.0-apache

3. 通过 Docker Compose 使用（示例）

创建 docker-compose.yml 文件：

version: '3'

services:
  xdebug:
    image: mileschou/xdebug:8.0
    volumes:
      - ./:/app
    working_dir: /app
    environment:
      - XDEBUG_MODE=coverage
      - XDEBUG_CLIENT_HOST=host.docker.internal
    command: php vendor/bin/phpunit --coverage-html coverage

启动服务：

docker-compose up

配置参数说明

Xdebug 的配置可通过 PHP 配置指令（-d 参数）或环境变量传递，常用配置参数：

• xdebug.mode：设置 Xdebug 运行模式，可选值：debug（调试）、coverage（代码覆盖率）、develop（开发辅助）等。
• xdebug.client_host：调试客户端主机地址，Docker 环境中通常需设置为 host.docker.internal（Windows/macOS）或宿主机 IP（Linux）。
• xdebug.client_port：调试客户端端口，默认 9003。

更多配置参数详见 Xdebug 官方文档。