PHPUnit代码覆盖率报告有效的关键是Xdebug在CLI下以coverage模式运行，需通过php -m和php -i验证；phpunit.xml路径以自身所在目录为基准，exclude须显式排除测试类，processUncoveredFiles必须设为true；PHP 8.1+应使用PHPUnit ≥9.3；覆盖率启用应通过PHP_XDEBUG_MODE=coverage临时设置。
PHPUnit生成有效代码覆盖率报告，核心不在phpunit.xml写得多漂亮，而在于Xdebug是否真正在CLI环境下以coverage模式运行。多数“报告为空”“全是0%”的问题，根源是Xdebug根本没被phpunit命令感知到。
确认Xdebug在CLI中已启用coverage模式
Web环境的phpinfo()页面毫无参考价值——phpunit走的是命令行PHP（CLI），必须单独验证：
- 运行
php -m | grep xdebug：无输出 = Xdebug未加载到CLI - 运行
php -i | grep "xdebug.mode"：输出必须包含coverage，且格式为debug,coverage或coverage（逗号间绝对不能有空格） - Xdebug 3已彻底废弃
xdebug.coverage_enable=1等旧配置，写了也无效，不报错但静默失效
phpunit.xml路径与范围配置要点
所有路径都以phpunit.xml所在目录为基准，不是项目根目录，也不是src/内部：
-
<include>只写真正要测的源码，例如：<directory suffix=".php">src/</directory> -
<exclude>必须显式排除测试辅助类，如src/Tests/、tests/或框架工具类，否则它们会被计入分母拉低覆盖率 - 务必设置
processUncoveredFiles="true"，否则未被任何测试执行的文件直接从报告中消失，你无法发现漏测盲区
版本兼容性与执行方式避坑
PHP 8.1+项目若用PHPUnit 9.2或更早版本，--coverage-html可能静默失败或输出空报告：
立即学习“PHP免费学习笔记（深入）”；
- 最低兼容门槛是 PHPUnit ≥ 9.3（推荐直接升级至10.x）
- 用
phpunit --version确认实际运行版本——Composer vendor bin、全局安装、Phar包可能混用，行为不一致 - 不要在php.ini中设
xdebug.start_with_request=yes：它会让所有CLI脚本变慢；覆盖率只需临时启用，例如：PHP_XDEBUG_MODE=coverage phpunit --coverage-html coverage-report
理解报告颜色背后的逻辑
HTML报告中某行标黄（部分覆盖），往往不是没执行，而是分支未走全：
-
if ($x) { ... } else { ... }中只触发了if分支，else未执行 → 行显示黄色，分支覆盖率不足 -
$this->assertContains('a', $arr)这行本身算“已执行”，但若$arr永远非空，else逻辑就永远不会被覆盖 - 行覆盖率和分支覆盖率是两套独立统计，需分别关注
