Hyperf是基于Swoole扩展的高性能PHP协程框架，其内置的命令行工具基于Symfony Console组件实现，覆盖了项目初始化、服务启动、代码生成、组件管理等各类开发场景，是开发者日常操作的核心入口之一。
运行Hyperf命令行工具的前置条件
在运行Hyperf的CLI命令之前，需要确保满足以下环境要求：
- 已经安装PHP 8.0及以上版本，且安装了Swoole扩展，扩展版本不低于4.5
- 已经通过Composer安装好Hyperf项目，项目根目录下存在
bin/hyperf.php文件 - 当前终端的工作目录已经切换到Hyperf项目的根目录
基础命令行工具的运行方式
Hyperf的命令行入口文件是项目根目录下的bin/hyperf.php，所有CLI命令都需要通过该文件执行，基础执行格式如下：
<?php // 基础命令执行格式，在终端中直接运行 php bin/hyperf.php [命令名称] [参数] [选项]
查看所有可用命令
如果不确定当前Hyperf版本支持哪些命令，可以先执行以下命令查看命令列表：
php bin/hyperf.php list
执行后会输出所有已注册的命令，包含命令名称、命令描述以及对应的参数说明。
查看单个命令的帮助信息
如果需要了解某个具体命令的使用方法，可以在命令后添加--help选项查看详细说明：
// 查看服务启动命令的帮助信息 php bin/hyperf.php start --help
常用CLI命令汇总
以下是Hyperf开发过程中最常用的CLI命令及对应作用说明：
| 命令名称 | 作用说明 | 示例 |
|---|---|---|
| start | 启动Hyperf服务，默认监听9501端口 | php bin/hyperf.php start |
| stop | 停止正在运行的Hyperf服务 | php bin/hyperf.php stop |
| restart | 重启Hyperf服务，会先停止再启动 | php bin/hyperf.php restart |
| server:watch | 启动热重载服务，代码修改后自动重启服务 | php bin/hyperf.php server:watch |
| gen:controller | 生成控制器文件 | php bin/hyperf.php gen:controller UserController |
| gen:model | 根据数据表生成模型文件 | php bin/hyperf.php gen:model User --table=user |
| migrate | 执行数据库迁移文件 | php bin/hyperf.php migrate |
| vendor:publish | 发布组件配置文件到项目配置目录 | php bin/hyperf.php vendor:publish hyperf/redis |
命令执行常见问题
在执行Hyperf CLI命令时，可能会遇到以下常见问题：
- 提示
php命令不存在：需要检查PHP是否已经添加到系统环境变量，或者使用PHP的完整路径执行命令，例如/usr/local/php/bin/php bin/hyperf.php start - 提示
bin/hyperf.php文件不存在：需要确认当前终端的工作目录是否为Hyperf项目根目录，可以通过pwd命令查看当前目录 - 启动服务后端口被占用：可以通过
netstat -tlnp | grep 9501查看占用端口的进程，停止对应进程后重新启动服务
自定义命令开发
如果内置命令无法满足需求，还可以基于Hyperf的命令行组件开发自定义命令，自定义命令需要继承HyperfCommandCommand类，示例代码如下：
<?php
declare(strict_types=1);
namespace AppCommand;
use HyperfCommandCommand;
use HyperfCommandAnnotationCommand as CommandAnnotation;
#[CommandAnnotation(name: "hello")]
class HelloCommand extends Command
{
// 命令描述
protected string $description = "输出hello world信息";
public function __construct()
{
parent::__construct("hello");
}
public function handle()
{
// 命令执行逻辑
$this->output->writeln("Hello Hyperf CLI");
}
}
开发完成后，执行php bin/hyperf.php hello就可以运行自定义命令，输出对应的内容。
HyperfHyperf_CLI命令行工具PHP修改时间：2026-06-19 04:45:19