在Docker的PHP 7.4环境安装Xdebug 3.1.5解决PHPUnit覆盖率问题

错误原因 #

你之前用docker-php-ext-install xdebug报错，是因为这个命令仅用于编译安装PHP源码包自带的扩展，而Xdebug属于第三方扩展，不在PHP源码的/usr/src/php/ext/目录下，所以找不到对应路径。pecl安装完成后，只需要启用扩展即可，不需要再用docker-php-ext-install。

正确安装与配置步骤 #

在GitLab流水线的脚本或Dockerfile中执行以下完整步骤：

1. 安装编译依赖
   首先需要安装编译Xdebug所需的工具和依赖包：

   apt-get update && apt-get install -y --no-install-recommends \
       gcc \
       make \
       php-dev \
       pkg-config \
       libssl-dev
   

2. 安装指定版本的Xdebug
   使用pecl安装Xdebug 3.1.5：

   pecl install xdebug-3.1.5
   

3. 启用Xdebug扩展
   用官方提供的docker-php-ext-enable命令启用已安装的Xdebug：

   docker-php-ext-enable xdebug
   

4. 配置Xdebug参数
   Xdebug 3的配置和旧版本差异较大，需要添加必要的配置项让PHPUnit正常识别覆盖率驱动。通过以下命令写入配置：

   echo "xdebug.mode=coverage" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
   echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
   

   • xdebug.mode=coverage：指定Xdebug运行在覆盖率模式，这是生成PHPUnit覆盖率报告的核心配置
   • xdebug.start_with_request=yes：确保请求启动时自动激活Xdebug

5. 验证安装结果
   执行以下命令确认Xdebug已正确安装并启用：

   php -v
   

   输出中应该包含类似以下内容：

   with Xdebug v3.1.5, Copyright (c) 2002-2022, by Derick Rethans

   也可以用php -m | grep xdebug查看是否存在xdebug模块。

GitLab CI脚本示例 #

如果是在.gitlab-ci.yml中配置，可参考以下片段：

test:
  image: php:7.4
  before_script:
    - apt-get update && apt-get install -y --no-install-recommends gcc make php-dev pkg-config libssl-dev
    - pecl install xdebug-3.1.5
    - docker-php-ext-enable xdebug
    - echo "xdebug.mode=coverage" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
    - echo "xdebug.start_with_request=yes" >> /usr/local/etc/php/conf.d/docker-php-ext-xdebug.ini
    - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer
    - composer install
  script:
    - phpunit --coverage-text --coverage-html=coverage

内容的提问来源于stack exchange，提问作者inventor96