PHPUnit 是 Composer 包测试默认选择，因其生态适配度高、无需抽象层、直接通过 vendor/bin/phpunit 运行；需在 require-dev 锁定版本，scripts 中用 "test": "phpunit"，并配置 autoload-dev 映射 tests/ 目录。
为什么 PHPUnit 是 Composer 包测试的默认选择
因为 Composer 生态中绝大多数包都用 PHPUnit，它的配置、断言、Mock 工具链和 CI 兼容性已经深度对齐 composer.json 的生命周期。你不需额外引入测试框架抽象层，直接在 vendor/bin/phpunit 运行即可验证类行为——前提是你的包不依赖 Laravel 或 Symfony 的完整容器。
如何在 composer.json 中正确声明测试依赖与脚本
测试依赖必须放在 require-dev 里，且版本要锁定（避免 CI 中因 minor 升级导致断言失败）。scripts 中的 test 命令应指向可执行路径，而非硬编码 ./vendor/bin/phpunit ——Composer 会自动解析 bin 路径。
-
phpunit版本建议用^9.6 || ^10.5：兼容 PHP 8.0–8.3，且避免 v11 引入的严格类型变更影响老逻辑 -
"test": "phpunit"比"test": "vendor/bin/phpunit"更健壮，尤其在使用composer install --no-dev后再切换环境时 - 加一条
"test-coverage": "phpunit --coverage-html=build/coverage"方便本地快速查漏
{
"require-dev": {
"phpunit/phpunit": "^9.6 || ^10.5",
"phpstan/phpstan": "^1.10"
},
"scripts": {
"test": "phpunit",
"test-coverage": "phpunit --coverage-html=build/coverage"
}
}
tests 目录结构与 autoloader 配置要点
Composer 默认不加载 tests/ 下的类，但 PHPUnit 需要自动发现测试用例。你必须在 composer.json 的 autoload-dev 中显式声明 psr-4 映射，否则 MyPackageTest 类会报 Class not found。
- 测试类文件名必须以
Test.php结尾（如StringHelperTest.php），PHPUnit 才能自动识别 -
autoload-dev的命名空间前缀建议与主代码一致，仅后缀加\Tests\，例如"MyPackage\Tests\": "tests/" - 不要把
tests/加进autoload（非 dev）——这会让最终用户无意中加载测试类，引发冲突
{
"autoload": {
"psr-4": {
"MyPackage\": "src/"
}
},
"autoload-dev": {
"psr-4": {
"MyPackage\Tests\": "tests/"
}
}
}
如何避免 PHPUnit 在 CI 中因路径或配置失效
本地跑通 ≠ CI 跑通。常见断点是 phpunit.xml 路径未被识别，或 --bootstrap 加载顺序错乱。最简方案是不用 XML 配置文件，全部通过命令行参数控制；若必须用，确保它放在项目根目录，并在 composer.json 的 scripts 中显式指定。
立即学习“PHP免费学习笔记（深入）”；
- CI 中优先用
phpunit --configuration phpunit.xml，而不是依赖默认查找逻辑 - 避免在
phpunit.xml中写绝对路径（如/home/runner/work/...），改用./或%ROOT_DIR%变量（v10+ 支持） - 如果测试依赖
vendor/autoload.php，别在phpunit.xml里重复bootstrap——Composer 自动加载已覆盖 - CI 环境中记得加
--no-coverage，否则 Xdebug 开销会让超时失败
真正容易被忽略的是：PHP 的 opcache.enable_cli=1 在某些 Docker 镜像中默认开启，会导致测试类修改后不重载，表现为“改了代码但测试仍过”。CI 中建议显式关掉：php -d opcache.enable_cli=0 vendor/bin/phpunit。
