本文详解 phpunit 代码覆盖率未纳入 ./module/*/src 等自定义目录的根本原因与实操修复方法，涵盖自动加载配置、pcov 冲突排查及 xml 配置优化，适用于 phpunit 9.5+ 与 xdebug 3 环境。

PHPUnit 的代码覆盖率报告仅显示 ./app 目录而忽略 ./module/*/src 下的文件，通常并非 配置本身失效，而是由两个关键前置条件未满足所致：源码未被自动加载（Autoloading） 和 PCOV 扩展干扰 Xdebug 覆盖率采集。

✅ 核心原因与修复步骤

1. 确保 Composer 自动加载已覆盖所有模块路径

PHPUnit 的代码覆盖率分析器（如 php-code-coverage）仅能追踪实际被加载并执行的 PHP 类文件。若 ./module/module-one/src 中的类未通过 Composer 自动加载机制注册（即未出现在 vendor/autoload.php 的映射中），即使路径写入 ，这些文件也不会被解析、执行或统计。

请在 composer.json 中为每个模块添加 PSR-4 自动加载规则，例如：

{
    "autoload": {
        "psr-4": {
            "ModuleOne\\": "module/module-one/src/",
            "ModuleTwo\\": "module/module-two/src/",
            "ModuleThree\\": "module/module-three/src/",
            "App\\": "app/"
        }
    }
}

✅ 修改后务必运行：

composer dump-autoload --optimize
# 或开发环境可省略 --optimize：
composer dump-autoload

⚠️ 注意：仅修改 phpunit.xml 不足以让 PHPUnit “感知” 新目录；Composer 的 autoloader 是覆盖率采集的前提。

2. 显式禁用 PCOV 扩展（尤其当 Xdebug 3 同时启用时）

您使用的环境（Xdebug 3.0.3 + php-code-coverage 1.0.8）明确要求 Xdebug 提供覆盖率数据。但若系统中同时启用了 pcov 扩展（常见于某些 Docker 镜像或预装环境），它会与 Xdebug 的 xdebug.coverage_enable 冲突，导致覆盖率采集静默失败——此时 PHPUnit 仍生成报告，但仅包含“已被加载”的文件（如 ./app 中因主逻辑调用而载入的部分），其余模块因未触发加载+执行而彻底消失。

请检查并禁用 PCOV：

# 查看已启用的扩展
php -m | grep -i pcov
# 或检查 php.ini
php --ini

在 php.ini 或 xdebug.ini 中确保：

; 禁用 PCOV（必须）
pcov.enabled=0

; 确保 Xdebug 覆盖率功能开启（Xdebug 3 默认关闭）
xdebug.mode=coverage
; （无需再设 xdebug.coverage_enable=1 —— mode=coverage 已隐含启用）

✅ 重启 Web 服务器或 CLI PHP 进程后验证：

php -v  # 应显示 Xdebug 版本，且无 PCOV 加载提示
php -i | grep -i "xdebug.mode"  # 输出应含 coverage

3. 补充建议：优化 phpunit.xml 配置（非必需但更健壮）

虽然多 条目语法合法，但为提升可维护性与兼容性，推荐改用 显式声明，或统一父目录配合 suffix 与 ignore 精确控制：

    
        ./app
        ./module/module-one/src
        ./module/module-two/src
        ./module/module-three/src
    
    
    
        ./tests
        ./vendor
    

✅ 验证流程（按顺序执行）

1. 更新 composer.json → 运行 composer dump-autoload
2. 设置 pcov.enabled=0 + xdebug.mode=coverage → 重启 PHP
3. 清理旧覆盖率缓存（如有）：rm -rf ./build/coverage
4. 运行：phpunit --coverage-html ./build/coverage
5. 检查 HTML 报告根目录是否变为 /（而非仅 /app），且各模块路径可见、行覆盖率非空。

? 提示：若仍不显示，可用 phpunit --debug 观察测试执行时是否实际加载了模块类；也可临时在某个模块类中 echo "loaded\n"; die(); 验证 autoload 是否生效。

遵循以上三步，即可彻底解决模块目录在 PHPUnit 覆盖率报告中“不可见”的问题——本质是让代码