PHPBench必须作为开发依赖安装，正确命令是composer require --dev phpbench/phpbench；全局安装无效，因依赖项目autoloader；命令位于vendor/bin/phpbench，需创建benchmarks目录及Bench后缀类文件。
PHP-Benchmark 不是标准库，也没有叫这个名字的主流包；你想用的其实是 phpbench/phpbench —— 它是 PHP 社区事实标准的基准测试框架，不是“PHP-Benchmark”。
为什么 composer require phpbench/phpbench 会失败或没效果
常见错误是直接运行 composer require phpbench/phpbench 后，敲 phpbench 命令提示 “Command not found” 或报错 Class 'PhpBench\Registry\Config' not found。
- 根本原因：没加
--dev，导致它被装进生产依赖，而phpbench只能在开发环境下通过vendor/bin/phpbench调用 - 更隐蔽的问题：全局安装（
composer global require）完全不可用——它依赖项目级 autoloader，global 环境下找不到vendor/autoload.php - Windows 用户容易写错路径：在
phpbench.json里用了反斜杠benchmarks\*.php，应统一用正斜杠benchmarks/*.php
正确安装与初始化步骤
必须在项目根目录执行以下命令：
-
composer require phpbench/phpbench --dev（注意顺序：phpbench/phpbench在前，--dev在后） - 确认生成了
vendor/bin/phpbench文件（可执行） - 创建
benchmarks/目录，并新建一个类文件，命名必须含Bench后缀，例如JsonBench.php - 类中方法名也必须以
Bench结尾，如jsonEncodeBench()，否则不被识别
最小可用示例：
立即学习“PHP免费学习笔记（深入）”；
<?php
use PhpBench\Benchmark\Metadata\Annotations\Iterations;
class JsonBench
{
public function jsonEncodeBench(): void
{
$data = ['foo' => 'bar', 'baz' => range(1, 100)];
json_encode($data);
}
}
运行时必须显式指定路径或 filter
PHPBench 默认不递归扫描子目录，也不自动发现 *Bench.php 文件 —— 这是最常被跳过的一步。
- 运行单个文件：
./vendor/bin/phpbench run benchmarks/JsonBench.php - 运行整个目录：
./vendor/bin/phpbench run benchmarks/ --filter="JsonBench" - 若配置了
phpbench.json，需明确写"path": "benchmarks/*.php"（不是**/*.php） - 想跑多轮取平均值？加参数：
--revs=1000 --iterations=5，表示每轮执行 1000 次，共 5 轮
版本兼容性与常见报错应对
PHPBench v2 和 v1 的注解、依赖结构差异大，升级后旧代码大概率崩。
- 报
Class 'PhpBench\Benchmark\Metadata\Annotations\Groups' not found？检查composer show phpbench/phpbench版本；v1 用@Groups，v2 要求完整命名空间，且部分注解已重命名（如@ParamProviders→@ParamProvider） - 和
phpunit/phpunit冲突？v2 依赖 PHPUnit 10+，若项目还在用 PHPUnit 9.5，要么锁死phpbench/phpbench:^1.2，要么统一升级 - CI 环境失败？绝不能依赖全局命令，所有调用必须走
./vendor/bin/phpbench，且确保composer install --no-interaction --prefer-dist已执行
真正麻烦的不是装不上，而是默认行为太“安静”：路径不对、后缀不符、没加 --dev、没写 --filter，它都静默退出，不报错也不输出结果。
