PHPUnit 代码覆盖率无法包含模块目录的解决方案

本文详解 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/"         }     } }

✅ 修改后务必运行：

立即学习“PHP免费学习笔记（深入）”；

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 “loadedn”; die(); 验证 autoload 是否生效。

遵循以上三步，即可彻底解决模块目录在 PHPUnit 覆盖率报告中“不可见”的问题——本质是让代码可加载 → 可执行 → 可追踪，而非单纯配置路径。