在 composer.json 的 scripts 中配置 coverage 脚本需指定 vendor/bin/phpunit 绝对路径，确保 phpunit/phpunit 在 require-dev 中，并添加 --coverage-html 和 --coverage-clover 参数；Xdebug 需显式启用（如 php -d zend_extension=xdebug.so），HTML 报告须通过本地 HTTP 服务访问，CI 中建议用 PCOV 替代 Xdebug 以提升性能。
composer.json 里怎么配 coverage 脚本
Composer 本身不生成覆盖率，它只是调用 PHPUnit 或其他工具；关键在 scripts 段配置好命令链。常见错误是直接写 phpunit --coverage-html=build/coverage 却没声明 phpunit 是 dev 依赖，导致 CI 环境报 Command "phpunit" is not defined。
正确做法是：确保 phpunit/phpunit 在 require-dev 中，然后在 scripts 里用 vendor/bin/phpunit 绝对路径（避免 PATH 问题）：
"scripts": {
"test": "vendor/bin/phpunit",
"coverage": "vendor/bin/phpunit --coverage-html=build/coverage --coverage-clover=build/logs/clover.xml"
}
- 不要省略
--coverage-clover——很多 CI 工具（如 Coveralls、Codecov）只认这个格式 -
build/coverage目录需有写权限，Docker 或 GitHub Actions 中常因工作目录不对而静默失败 - 如果项目用 PHP 8.1+ 且装了 xdebug 3，得额外加
--coverage-php=build/logs/coverage.php才能导出原始数据供其他工具处理
为什么 vendor/bin/phpunit 执行时报 Xdebug 未启用
覆盖率依赖 Xdebug（或 PCOV），但 Composer 脚本默认不继承 shell 的 PHP 配置。现象是命令看似成功，但 build/coverage 下只有空文件夹，或报 No code coverage driver available。
解决方式不是改 php.ini 全局配置，而是让脚本显式启用扩展：
- Linux/macOS：在
scripts中改用php -d zend_extension=xdebug.so vendor/bin/phpunit ... - Windows：用
php -d zend_extension=php_xdebug.dll vendor/bin/phpunit ... - 更稳妥的是统一用
php -m | grep -i xdebug确认模块名，再填进-d参数 - 若用 PCOV（轻量替代方案），需确保 PHP 编译时带
--enable-pcov，且运行时加-d extension=pcov.so
coverage 命令跑完却打不开 HTML 报告
生成的 index.html 用浏览器双击打开会因 CORS 被拒，显示空白页或 JS 报错 Failed to load resource: net::ERR_FILE_NOT_FOUND。这不是 Composer 或 PHPUnit 的 bug，是现代浏览器限制 file:// 协议加载本地资源。
临时解决只需起个最小 HTTP 服务：
- PHP 自带：运行
php -S localhost:8000 -t build/coverage，然后访问http://localhost:8000 - Python 3：
python3 -m http.server 8000 --directory build/coverage - 别用
open index.html或 VS Code Live Server 插件——它们可能读错相对路径，导致 CSS/JS 404
CI 环境里 coverage 脚本总超时或内存溢出
GitHub Actions 或 GitLab CI 默认内存有限，Xdebug + 大项目容易触发 Fatal error: Allowed memory size exhausted 或超时中断。这不是代码问题，是工具链配置过重。
精简策略优先级如下：
- 禁用 Xdebug 的调试功能：加
-d xdebug.mode=coverage（Xdebug 3.1+），而不是默认的develop,coverage - 跳过非核心目录：在
phpunit.xml中用<whitelist></whitelist>显式指定src/，别依赖自动发现 - 用
--coverage-filter=src/替代全量扫描，尤其当项目含 tests/ fixtures/ vendor/ 子目录时 - CI 中可考虑换 PCOV：它比 Xdebug 快 3–5 倍，且内存占用低，但仅支持 PHP 7.4+
覆盖率报告本身不难生成，难的是让每一步都可复现、不依赖本地环境——路径、扩展、权限、协议，漏一个就卡住。
