<p>composer test 能跑起来只取决于三件事：装对版本的 PHPUnit、phpunit.xml.dist 放在项目根目录且 bootstrap 路径正确、scripts 中命令写为 "test": "vendor/bin/phpunit" 并用 -- 透传参数。</p>
直接说结论：composer test 能跑起来，只取决于三件事——装对版本的 PHPUnit、phpunit.xml.dist 放对位置、scripts 里写对命令。其他都是细节，但错一个就卡住。
装 PHPUnit 必须带版本号，且匹配当前 PHP 版本
不指定版本号（比如 composer require --dev phpunit/phpunit）是高频翻车点。Composer 可能拉到 PHPUnit 11，而你的 PHP 是 8.1 —— 立刻报 Declaration of PHPUnitFrameworkTestCase::setUp(): void must be compatible 这类致命错误。
- PHP 7.4 或 8.0 → 用
composer require --dev phpunit/phpunit:^9.6 - PHP 8.1（如 Laravel 10+）→ 用
composer require --dev phpunit/phpunit:^10.5 - PHP 8.2+ 且确认不用
phpunit-skeleton-generator→ 可试^11.0，但别盲目@latest - 装完立刻验证：
./vendor/bin/phpunit --version，输出版本号才说明真装进去了
phpunit.xml.dist 必须在项目根目录，且 bootstrap 路径要可访问
PHPUnit 默认只读当前工作目录下的 phpunit.xml 或 phpunit.xml.dist。名字差一个字符、放错层级（比如丢进 config/）、或者被 IDE 加了 --no-configuration 参数，都会导致配置静默失效 —— 表现就是测试文件找不到、TestCase 类报 Class not found。
- 文件必须和
composer.json同级（即项目根目录） -
bootstrap="vendor/autoload.php"是底线配置，不能写成./vendor/autoload.php或../vendor/autoload.php - 别用已废弃的
<whitelist>；覆盖率要写成<coverage><include><directory>src</directory></include></coverage> - 如果用 ThinkPHP，官方扩展会自动生成
tests/bootstrap.php，此时bootstrap应设为tests/bootstrap.php，不是vendor/autoload.php
composer.json 的 scripts 必须用 vendor/bin/phpunit，参数透传要加双横线
写成 "test": "phpunit" 看似简洁，实际跨平台不稳：Windows 找不到命令，Linux/macOS 可能调到全局旧版，配置全乱。更糟的是，composer test --filter=MyTest 不加双横线，--filter 会被 Composer 自己解析掉，根本传不到 PHPUnit。
立即学习“PHP免费学习笔记（深入）”；
- 统一写成
"test": "vendor/bin/phpunit"—— Composer 会自动选.bat（Windows）或可执行文件（其他系统） - 想传参数必须用
composer test -- --filter=MyTest，第一个--是分界符 - 若脚本指向 PHP 文件（如
"test": "php test-runner.php"），参数从$argv[2]开始取；更可靠的是读getenv('COMPOSER_ARGS') - CI 场景下建议加
--no-coverage，避免因没装 xdebug 导致失败
autoload-dev 映射没配或没 dump-autoload，测试类就加载不了
即使 PHPUnit 装好了、配置也对，如果你的业务类在 src/ 下，而 composer.json 里没声明 "autoload-dev": {"psr-4": {"Tests\": "tests/"}}，或者改了 autoload 没运行 composer dump-autoload，那测试里 new AppServiceCalculator() 就会报 Class not found。
- 确保
autoload和autoload-dev都有合理映射，比如"App\": "src/"和"Tests\": "tests/" - 改完 composer.json 后，一定执行
composer dump-autoload - ThinkPHP 用户注意：
topthink/think-testing会帮你补tests/bootstrap.php，但它不替代你配 autoload
真正麻烦的从来不是“怎么装”，而是“为什么 test 命令没反应”“为什么 TestCase 找不到”“为什么我的 Service 类死活加载不了”——这些问题背后，90% 是 bootstrap 路径错、autoload 没生效、或者 PHPUnit 版本和 PHP 版本硬性不兼容。盯住这三点，比调半天断言更有用。
