hyperf 命令不执行或报错多因初始化未完成、依赖缺失或配置错误；需确保 composer install 完成、bin/hyperf.php 存在可读、php≥8.1 且 swoole 协程启用，再依步骤排查命令注册、数据库配置、迁移路径及日志级别等问题。
php bin/hyperf.php 命令不执行或报错
直接运行 php bin/hyperf.php 却没输出、卡住、或提示 Class not found，大概率是项目未完成初始化或依赖未装全。Hyperf 的命令行入口不是“即装即用”，它依赖 composer install 后生成的自动加载文件和容器配置。
确保以下三点已做完：
-
composer install --no-dev（生产环境）或composer install（开发环境）已成功执行，且无 fatal error -
bin/hyperf.php文件存在且可读，权限正常（非 Windows 系统下注意换行符是否为 LF） - PHP 版本 ≥ 8.1，且
swoole扩展已启用协程支持：php --ri swoole中必须含support coroutines: enabled
查看所有可用命令及子命令参数
Hyperf 的命令系统基于 Symfony Console 封装，但默认只显示高频命令；完整列表需主动触发。
常用查法：
- 查全部命令：运行
php bin/hyperf.php（不带任何子命令），会列出已注册的命令组，如migrate、gen、server:watch - 查某命令帮助：比如看迁移支持哪些选项，运行
php bin/hyperf.php migrate --help，会明确列出--step、--rollback、--pretend等参数含义 - 注意：部分命令（如
gen:command）在首次运行前需先composer require hyperf/command，否则提示Command "gen:command" is not defined
执行迁移命令时常见失败点
php bin/hyperf.php migrate 看似简单，但实际失败多因配置或环境错位，而非语法错误。
典型问题与应对：
- 报错
Database connection [default] not configured：检查config/autoload/database.php是否正确定义了default连接，并确认数据库服务已启动、账号密码正确 - 迁移文件没被扫描到：迁移文件必须放在
app/Migrations/目录下，命名格式严格为YYYY_MM_DD_HHMMSS_describe_table.php（如2024_01_01_000000_create_users_table.php），且类需继承Hyperf\Database\Migrations\Migration - 想预览 SQL 但没生效：加
--pretend参数后仍执行了迁移，说明你可能误用了--force或环境变量APP_ENV=prod导致跳过确认逻辑；建议始终搭配--pretend和-v（verbose）一起用
自定义命令执行时报错 “Commands registered by …” 后无输出
新建的命令类（如 DemoCommand）能注册成功，但 handle() 方法里的 echo 或 $this->line() 不显示，通常不是代码问题，而是日志级别拦截了。
关键检查项：
- 确认
config/autoload/logger.php或config/config.php中StdoutLoggerInterface::class的log_level数组包含LogLevel::INFO（$this->line()默认用 INFO 级别） - 避免在
handle()中使用exit()或die()—— 这会中断 Hyperf 的命令生命周期钩子，导致后续AfterExecute事件不触发，调试信息丢失 - 如果命令需要访问 DI 容器服务，务必通过构造函数注入（如
ContainerInterface $container），不要在方法内用make()，否则可能因作用域问题拿不到实例
php bin/hyperf.php xxx 背后，可能牵扯到 Swoole 初始化、注解解析、DI 构建、日志通道配置四个环节——任一环节静默失败，都会让命令“看起来没反应”。调试时优先看 php bin/hyperf.php help 是否能出结果，再逐层向下验证。php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
