phpunit 应本地安装而非全局，因全局会污染环境、版本冲突、路径权限问题且ci/cd不可靠；本地执行 composer require --dev phpunit/phpunit ^10，用 vendor/bin/phpunit 运行，并配 phpunit.xml 与 autoload-dev。
PHPUnit 不再推荐通过 composer global 全局安装，本地项目级安装才是稳定、可复现、无权限冲突的正确方式。
为什么不能用 composer global require phpunit/phpunit
全局安装会污染系统环境，不同项目可能依赖不同版本的 PHPUnit（如 PHP 7.4 项目需 PHPUnit 9，PHP 8.2 项目需 PHPUnit 10），全局只有一个版本会导致测试失败或命令找不到。另外，composer global 在某些系统（如 macOS M1/M2 + Homebrew PHP）下常因路径未加入 $PATH 或权限问题导致 phpunit 命令不可用。
- 实际错误现象：
Command "phpunit" not found或Class 'PHPUnitFrameworkTestCase' not found - CI/CD 流水线中全局安装不可靠，必须显式声明依赖
- 团队协作时，全局状态无法被
composer.lock锁定，极易引发环境不一致
本地安装：在项目根目录执行
进入你的 PHP 项目根目录（含 composer.json），运行：
composer require --dev phpunit/phpunit ^10
说明：
立即学习“PHP免费学习笔记（深入）”；
-
--dev表示仅开发环境需要，不会打入生产依赖 -
^10指定主版本兼容范围（自动匹配 10.x 最新稳定版）；若项目仍在用 PHP 7.3–8.0，改用^9.6 - 安装后，可执行
vendor/bin/phpunit（Linux/macOS）或vendorinphpunit（Windows） - 无需配置系统
$PATH，所有成员执行同一路径即可
快速验证是否装好 + 基础配置 phpunit.xml
新建 phpunit.xml 放在项目根目录，内容如下（适配 PHPUnit 10+）：
<?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"
colors="true"
verbose="true">
<testsuites>
<testsuite name="default">
<directory>tests</directory>
</testsuite>
</testsuites>
</phpunit>
然后创建一个最简测试：
- 建目录
tests/ExampleTest.php - 内容为：
<?php
use PHPUnitFrameworkTestCase;
final class ExampleTest extends TestCase
{
public function testTrueIsTrue(): void
{
$this->assertTrue(true);
}
}
执行：vendor/bin/phpunit —— 应看到绿色 PASSED 输出。
常见坑：autoload 和命名空间没对上
如果报错 Class "ExampleTest" could not be found 或 Cannot declare class, because the name is already in use，大概率是以下之一：
-
composer.json中未配置"autoload-dev"，导致测试类无法被自动加载（尤其自定义命名空间时） -
tests/目录未在phpunit.xml的<directory></directory>中声明，或路径拼写错误（如写成test/少了s） - 测试文件名不以
Test.php结尾，或类名未与文件名严格一致（如ExampleTest.php必须含class ExampleTest） - 使用了
psr-4autoload 但未映射tests/到测试命名空间（可加："autoload-dev": { "psr-4": { "Tests\": "tests/" } }）
本地安装 + 显式路径调用 + XML 配置三者绑定，才是可交付、可重现的 PHPUnit 使用基础。别省那几秒去碰 global。
