必须先验证PHP（≥7.4）和Composer（≥2.2）可用，检查php.ini中phar、json未被禁用；再执行composer require --dev phpunit/phpunit并用./vendor/bin/phpunit --generate-configuration生成phpunit.xml.dist，确保bootstrap指向vendor/autoload.php。
确认PHP和Composer是否就绪
PHPUnit依赖PHP运行时和Composer包管理，这两者必须先验证可用。很多“测试跑不起来”的问题其实卡在这一步。
- 执行
php -v，确保输出 PHP 版本 ≥ 7.4（PHPUnit 9.x 起最低要求；若用 PHPUnit 10，需 PHP ≥ 8.1） - 执行
composer --version，确认 Composer 已安装且不是太旧（建议 ≥ 2.2） - 检查
php.ini中是否禁用了phar或json扩展——PHPUnit 加载测试用例和解析配置都依赖它们，禁用会导致Class 'PHPUnit\Framework\TestCase' not found
安装PHPUnit并生成基础配置
不要全局安装 PHPUnit，它应该作为项目级开发依赖存在，否则不同项目间版本冲突会非常头疼。
- 在项目根目录运行：
composer require --dev phpunit/phpunit（自动选兼容当前 PHP 的最新稳定版） - 紧接着运行：
./vendor/bin/phpunit --generate-configuration，按提示生成phpunit.xml.dist（不是phpunit.xml，后者常被.gitignore忽略） - 生成后检查
bootstrap值是否指向vendor/autoload.php；若项目用了自定义自动加载（如 ThinkPHP 或 Laravel），可能需要手动改写bootstrap指向其测试引导文件
编写第一个测试并验证执行路径
很多人写完测试却报 Class not found 或 No tests executed，多半是目录结构或命名没对上。
- 按 PHPUnit 默认约定：测试文件放在
tests/目录下，类名以Test结尾（如CalculatorTest.php），类内方法以test开头或带@test注解 - 确保测试类
use PHPUnit\Framework\TestCase;，且继承TestCase - 运行命令要带路径：
./vendor/bin/phpunit tests/（注意末尾斜杠，否则可能只匹配单个文件） - 如果提示
Could not find driver，说明测试中用了数据库但未启用 PDO 扩展——这不是 PHPUnit 本身的问题，而是环境缺失
常见失败场景与快速定位方式
实际调试时，错误信息往往藏在表层之下，直接看报错文字容易误判。
立即学习“PHP免费学习笔记（深入）”；
-
ParseError: syntax error, unexpected Token：大概率是 PHP 版本低于测试代码语法要求（比如用了 PHP 8.0 的联合类型，但环境是 7.4） -
Warning: require_once(.../TestCase.php): failed to open stream：autoload 失败，检查composer.json的"autoload"和"autoload-dev"是否覆盖了tests/目录 - 测试通过但覆盖率报告为空：确认
phpunit.xml.dist中<filter><whitelist>下的<directory>指向的是实际源码路径（如src/），而非tests/
真正麻烦的不是装不上，而是装上了却不知道哪一层在拦截——PHP 版本、Composer autoload、phpunit.xml 路径、测试命名规则，四者只要一个错位，就会静默失败或报错偏移。
