启用Xdebug后Laravel/Pest并行测试崩溃，无法生成代码覆盖率

问题现象 #

• 启用Xdebug生成代码覆盖率时，单跑单元测试./vendor/bin/pest --suite unit可正常执行并生成报告
• 全量并行测试时worker直接崩溃；关闭Xdebug后并行测试恢复正常
• 非并行模式下运行全量测试，无最终测试总结，PHPUnit报告也无法更新
• 日志中出现SQLSTATE[HY000]: General error: 2006 MySQL server has gone away错误，排查发现启用Xdebug后PHP容器内存耗尽重启，关闭Xdebug时内存占用远低于限制
• 尝试添加tearDown处理内存泄漏、注释旧PHPUnit格式测试，均无效果

解决措施 #

1. 缩小Xdebug覆盖率收集范围 #

Xdebug默认会收集所有文件的覆盖率数据（包括vendor目录），这会大幅占用内存。通过配置限制仅收集业务代码：

• 在PHP配置文件（php.ini或xdebug.ini）中添加：

xdebug.mode = coverage
xdebug.filter = "+app/src/*,-vendor/*,-tests/*"

• 或者在phpunit.xml里配置覆盖率白名单：

<filter>
    <whitelist processUncoveredFilesFromWhitelist="true">
        <directory suffix=".php">./app/src</directory>
        <exclude>
            <directory suffix=".php">./vendor</directory>
            <directory suffix=".php">./tests</directory>
        </exclude>
    </whitelist>
</filter>

2. 调整并行测试配置与内存限制 #

启用Xdebug后每个worker的内存占用会显著上升，需降低worker数量并调高内存配额：

• 在pest.php中减少并行worker数：

uses(ParallelTesting::class)->options([
    'workers' => 2, // 根据容器实际内存调整，比如从4个降至2个
]);

• 调高PHP内存限制（php.ini）：

memory_limit = 1G

• 调整Docker容器内存分配（docker-compose.yml）：

services:
  php:
    deploy:
      resources:
        limits:
          memory: 2G

3. 修复MySQL连接超时问题 #

容器内存耗尽重启会导致MySQL连接中断，可通过调整MySQL参数缓解：

• 在MySQL配置文件中设置：

wait_timeout = 3600
interactive_timeout = 3600

• 在测试基类中确保每个测试用例结束后主动关闭数据库连接，避免连接长时间闲置。

4. 仅启用Xdebug覆盖率模式 #

避免同时启用Xdebug的调试功能，启动测试时通过环境变量指定仅用覆盖率模式：

XDEBUG_MODE=coverage ./vendor/bin/pest --parallel

5. 定位测试代码中的隐性内存泄漏 #

通过内存监控定位高内存占用的测试用例：

• 在测试基类中添加内存监控代码：

protected int $startMemory;

public function setUp(): void
{
    parent::setUp();
    $this->startMemory = memory_get_usage(true);
}

public function tearDown(): void
{
    parent::tearDown();
    $endMemory = memory_get_usage(true);
    // 标记内存占用超过100M的测试
    if ($endMemory - $this->startMemory > 1024 * 1024 * 100) {
        error_log("高内存测试用例: " . $this->getName());
    }
}

针对标记出的测试用例优化，比如避免创建大量对象、及时释放资源。

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