必须加--dev，否则PHPUnit被误写入require导致生产环境缺失；PHP 7.4用^9.6，8.2+可用^10.5或^11.0；phpunit.xml须置于根目录且命名正确，autoload-dev映射与命名空间需严格匹配。
composer require --dev phpunit/phpunit 必须加 --dev
不加 --dev 会导致 PHPUnit 被写进 require 段，上线执行 composer install --no-dev 时直接缺失，CI 流水线跑测试会直接报 Command not found: phpunit。这不是权限或路径问题，是依赖根本没装上。
PHP 版本和 PHPUnit 版本必须对齐：
- PHP 7.4 → 用
composer require --dev phpunit/phpunit:^8.5或^9.6（LTS） - PHP 8.0–8.1 → 推荐
^9.6，文档全、兼容稳 - PHP 8.2+ → 可选
^10.5或^11.0，但注意^11.0已移除部分旧断言方法
别信 composer require --dev phpunit/phpunit 不写版本号——Composer 可能拉到与当前 PHP 不兼容的主版本，比如给 PHP 7.4 装了 ^10.x，composer install 直接失败。
phpunit.xml 必须放在项目根目录且名字不能错
PHPUnit 默认只识别当前工作目录下的 phpunit.xml 或 phpunit.xml.dist。文件名多一个空格、少一个点、放错层级（比如丢进 tests/ 里），它就静默回退到默认扫描逻辑：只找当前目录下 *Test.php 文件，完全忽略你写的配置。
立即学习“PHP免费学习笔记（深入）”；
常见失效场景：
- IDE（如 PHPStorm）默认加
--no-configuration参数，导致phpunit.xml被跳过 -
<directory></directory>写成./tests—— 实际应为tests，因为路径解析以配置文件所在目录为基准 - 用了已废弃的
<whitelist></whitelist>（PHPUnit ≥9.3），覆盖率报告始终为空；必须改用<coverage><include><directory>src</directory></include></coverage>
最小可用配置（存为项目根目录下的 phpunit.xml）：
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
bootstrap="vendor/autoload.php">
<testsuites>
<testsuite name="default">
<directory>tests</directory>
</testsuite>
</testsuites>
<coverage/>
</phpunit>
autoload-dev 和命名空间必须同时对得上
装完 PHPUnit、配好 phpunit.xml，还报 Class 'TestsUnitExampleTest' not found？大概率是 autoload-dev 没生效，或类路径与命名空间不匹配。
检查三件事：
-
composer.json中autoload-dev是否包含"Tests\": "tests/"映射 - 是否运行过
composer dump-autoload—— 改完autoload-dev后这步不可跳过 - 测试文件路径和命名空间是否严格对应：文件
tests/Unit/ExampleTest.php→ 命名空间必须是namespace TestsUnit;
漏掉任意一点，自动加载就断在半路，./vendor/bin/phpunit 启动时直接抛 Class not found，而不是进入测试逻辑。
永远用 ./vendor/bin/phpunit 启动，别碰全局 phpunit
全局安装 phpunit（composer global require phpunit/phpunit）看似省事，实则埋雷：它会忽略当前项目的 phpunit.xml 和 vendor/autoload.php，导致测试类找不到、被测代码无法加载、断言失败堆栈混乱。
正确启动方式只有这一种：
- Linux/macOS：
./vendor/bin/phpunit - Windows：
vendorinphpunit
如果提示 Command not found，先确认 vendor/bin/ 目录是否存在，再执行一次 composer install。别试图把 vendor/bin 加进 $PATH —— 不同项目可能依赖不同版本的 PHPUnit，混用必出问题。
真正卡住人的，从来不是不会写 $this->assertEquals()，而是 composer require 少了个 --dev、phpunit.xml 多了个点、或者以为全局装一次就能一劳永逸。
