PHP代码覆盖率报告生成失败，90%以上因Xdebug 3未以coverage模式运行或与PHPUnit 10.5+不匹配；需确认php.ini中xdebug.mode=coverage、CLI环境加载正确、禁用PCOV冲突，并用--coverage-filter指定源码路径。
PHP 代码覆盖率报告生成失败，90% 以上情况是 Xdebug 3 配置未生效或与 PHPUnit 不匹配。重点不是装了 Xdebug，而是它是否以 coverage 模式运行，并被 PHPUnit 正确识别。
确认 Xdebug 3 已启用 coverage 模式
Xdebug 3 彻底重构了配置逻辑，xdebug.coverage_enable 等旧参数已废弃。必须用 xdebug.mode 显式开启：
- 在
php.ini（CLI 环境）中添加或修改：xdebug.mode=coverage - 确保没有其他冲突模式，例如不要同时设
xdebug.mode=debug,coverage（除非真需要调试+覆盖，但会拖慢速度） - 执行
php -v查看是否显示with Xdebug v3.x.x；再运行php --ri xdebug | grep mode，输出应含mode => coverage - 若用 Docker 或 PHP-FPM，注意 CLI 和 Web 的 php.ini 是两套，覆盖率只依赖 CLI 配置
phpunit 执行报 “No code coverage driver is available”
这是最常见错误，说明 PHPUnit 找不到可用的覆盖率驱动。原因和解法如下：
- PHPUnit 版本过低：PHP 8.5 必须用 PHPUnit ≥ 10.5，旧版不识别 Xdebug 3 的 coverage API。运行
./vendor/bin/phpunit --version核对 - Xdebug 扩展未加载到 CLI：运行
php -m | grep xdebug，无输出则需检查zend_extension路径是否正确（如zend_extension=/usr/lib/php/20241212/xdebug.so），路径可通过php --ini和php-config --extension-dir确认 - 启用了 PCOV 但未禁用 Xdebug：PCOV 和 Xdebug 不能共存于同一 CLI 进程。若已装 PCOV，临时注释掉
extension=pcov.so再试 - phpunit.xml 中误配了 coverage 驱动：新版 PHPUnit 不需要手动指定 driver，删掉类似
<coverage><driver>xdebug</driver></coverage>的配置
生成 HTML 报告但全是灰色/无数据
报告生成成功，但文件列表为空或所有行未高亮，说明代码未被实际执行（不是工具问题，是测试没跑进目标目录）：
立即学习“PHP免费学习笔记（深入）”；
-
--whitelist路径写错：命令中用--whitelist src/，但实际代码在app/或lib/；建议改用--coverage-filter src/（PHPUnit 10+ 推荐） - 测试用例未加载到待测类：检查命名空间、自动加载（Composer autoload）、
use语句是否匹配，可先运行单个测试./vendor/bin/phpunit tests/ExampleTest.php看是否报 ClassNotFound - 测试本身没调用任何业务方法：比如空的
testSomething()或只做了$this->assertTrue(true)，自然不会触发 src 下任何代码 - PHP 8.5 strict_types 影响：若 src 文件顶部有
declare(strict_types=1)，而测试中传参类型不符，会直接抛Fatal error中断执行，导致覆盖率中断。加--debug参数运行看是否卡在某处
红色/黄色标记行看不懂或不符合预期
HTML 报告里红（未执行）、黄（分支未全走）是可靠信号，但需结合 PHP 8.5 新特性解读：
- 联合类型中的
false分支：如函数返回string|false，只测了字符串返回，漏了false场景，就会标黄——需补$this->assertFalse($result)或异常断言 - null 安全操作符
?->：若对象为 null，整条链不执行，对应行会变红。要专门构造 null 输入来覆盖 -
match表达式缺default或未执行：即使语法允许省略 default，覆盖率也会把无 default 的 match 整体标红；有 default 也要确保测试中真走到它 - 隐式类型转换被禁用：PHP 8.5 禁用
"1" + 2类运算，若旧测试依赖此行为，现在会报TypeError，导致后续代码不执行——这类错误在报告中表现为“上游红，下游全灰”
