<p>在 composer.json 的 "scripts" 中添加 "test": "vendor/bin/phpunit --configuration phpunit.xml.dist" 即可配置 PHPUnit 脚本，需确保 phpunit.xml.dist 存在且路径正确，并通过 composer test -- [args] 透传参数。</p>
composer.json 里怎么配 PHPUnit 脚本
直接在 "scripts" 字段里加一条命名脚本就行，比如叫 "test"。Composer 不会自动识别测试命令，必须显式声明，否则 composer test 会报错“Script does not exist”。
常见写法是调用 phpunit 可执行文件，路径可以是全局安装的，也可以是项目本地的 vendor/bin/phpunit——后者更安全，避免环境差异导致版本不一致。
- 推荐用
vendor/bin/phpunit，哪怕你全局装了也优先走本地 - 如果项目根目录没有
phpunit.xml或phpunit.xml.dist，得手动指定配置文件路径，否则 PHPUnit 会按默认规则找，容易漏掉--bootstrap或测试目录 - 加
--no-ansi可避免 CI 环境下颜色输出乱码
{
"scripts": {
"test": "vendor/bin/phpunit --configuration phpunit.xml.dist"
}
}
运行 composer test 时实际发生了什么
Composer 并不执行 PHPUnit 逻辑，它只是启动一个子进程去跑你写的命令字符串。这意味着：环境变量、工作目录、PHP 版本、扩展加载，全由当前 shell 环境决定，Composer 自身不干预。
典型陷阱是：本地 composer test 成功，CI 上失败。往往因为 CI 使用的 PHP 没开 mbstring 或 xml 扩展，而 PHPUnit 启动时没报明确错误，只卡在 autoload 阶段或抛出 Class 'PHPUnit\Framework\TestCase' not found 这类误导性提示。
立即学习“PHP免费学习笔记（深入）”；
- 检查方式：在脚本里临时加
php -v && php -m | grep -E 'mbstring|xml|json' - 如果 PHPUnit 是通过
require-dev安装的，确保composer install --no-interaction --prefer-dist已执行，否则vendor/bin/phpunit根本不存在 - Windows 下注意路径分隔符，
vendor\bin\phpunit在某些旧版 Composer 里无法被正确解析，坚持用正斜杠vendor/bin/phpunit
phpunit 命令参数怎么传给 Composer 脚本
Composer 的脚本支持参数透传，但语法要对：必须用双横线 -- 分隔。比如你想只跑某个测试类，不能写 composer test tests/Unit/HelperTest.php，那会报错“Unknown argument”。正确写法是：
composer test -- tests/Unit/HelperTest.php
这个 -- 后面的所有内容，会被原样拼到脚本命令末尾。所以你的 "test" 脚本定义里最好预留 $@ 占位（仅限 Linux/macOS）或使用跨平台兼容写法。
- 跨平台安全写法：
"test": "vendor/bin/phpunit --configuration phpunit.xml.dist"，然后靠--透传 - 想默认带
--verbose但又允许覆盖，可写成"test": "vendor/bin/phpunit --configuration phpunit.xml.dist --verbose"，再用-- --debug强制覆盖为 debug 模式（PHPUnit 支持后置参数覆盖前置） - 别在脚本里硬编码
--filter，除非你确定每次都要跑同一批测试；过滤逻辑应交给开发人员手动传参
为什么 phpunit.xml.dist 比命令行参数更可靠
命令行参数易丢失、难维护、不支持条件判断；而 phpunit.xml.dist 是 PHPUnit 原生配置载体，能精确控制 bootstrap 文件、测试目录、覆盖率、环境变量等。尤其当项目有多个测试类型（unit/integration/browser），靠 XML 的 <testsuites> 分组比反复改命令行更清晰。
一个最小可用的 phpunit.xml.dist 至少该包含三块：测试目录、bootstrap 入口、PHP 配置。漏掉 bootstrap 很可能导致 Class not found，因为 PHPUnit 默认不自动加载 vendor/autoload.php。
<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.5/phpunit.xsd"
bootstrap="vendor/autoload.php"
colors="true">
<testsuites>
<testsuite name="Unit">
<directory>tests/Unit</directory>
</testsuite>
</testsuites>
</phpunit>
XML 文件名必须严格匹配脚本里写的 --configuration 参数，大小写、扩展名都不能错；Composer 不校验这个文件是否存在，只负责把字符串传给 PHPUnit。
