本文详解 phpunit 代码覆盖率未纳入 ./module/*/src 等自定义目录的根本原因与实操修复方法，涵盖自动加载配置、pcov 冲突排查及 xml 配置优化，适用于 phpunit 9.5+ 与 xdebug 3 环境。
PHPUnit 的代码覆盖率报告仅显示 ./app 目录而忽略 ./module/*/src 下的文件，通常并非
✅ 核心原因与修复步骤
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 配置（非必需但更健壮）
虽然多
./app ./module/module-one/src ./module/module-two/src ./module/module-three/src ./tests ./vendor
✅ 验证流程（按顺序执行）
- 更新 composer.json → 运行 composer dump-autoload
- 设置 pcov.enabled=0 + xdebug.mode=coverage → 重启 PHP
- 清理旧覆盖率缓存（如有）：rm -rf ./build/coverage
- 运行：phpunit --coverage-html ./build/coverage
- 检查 HTML 报告根目录是否变为 /（而非仅 /app），且各模块路径可见、行覆盖率非空。
? 提示：若仍不显示，可用 phpunit --debug 观察测试执行时是否实际加载了模块类；也可临时在某个模块类中 echo "loaded\n"; die(); 验证 autoload 是否生效。
遵循以上三步，即可彻底解决模块目录在 PHPUnit 覆盖率报告中“不可见”的问题——本质是让代码可加载 → 可执行 → 可追踪，而非单纯配置路径。
