Hyperf自动加载问题表现为类找不到、命令失败等，主因是PSR-4路径错误、缓存未清、命名不规范；需检查composer.json映射、统一大小写与命名、运行composer dump-autoload -o、清空Hyperf runtime缓存并验证class_exists。
Hyperf 的自动加载问题通常表现为类找不到（Class not found）、命令执行失败、服务启动报错，或热更新后旧代码仍生效。核心原因多出在 Composer 自动加载配置、PSR-4 映射路径错误、缓存未刷新或文件命名/结构不规范。下面从常见场景出发，给出可落地的排查和操作步骤。
检查 composer.json 中的 autoload 配置是否正确
Hyperf 默认使用 PSR-4 自动加载，需确保 composer.json 的 autoload 和 autoload-dev 区块路径与实际目录结构严格一致。例如：
- 若你的应用代码在
app/Controller，对应命名空间应为AppController，且composer.json中必须有："App\": "app/" - 控制器类文件名必须匹配类名，如
app/Controller/UserController.php内必须声明class UserController - 修改后务必运行
composer dump-autoload -o（加-o启用优化模式）生成新映射
确认类文件路径与命名空间是否完全匹配
Hyperf 对大小写敏感（尤其在 Linux/macOS 环境），常见错误包括：
- 文件夹名写成
controller（小写），但命名空间写AppController→ 应统一为 PascalCase，即Controller - 类文件用了中文或特殊字符命名（如
用户控制器.php）→ 必须是合法英文文件名 +.php后缀 - 命名空间末尾多写了反斜杠，如
namespace AppController;（末尾 不必要，虽不报错但易引发混淆）
清理所有缓存并验证加载逻辑
Hyperf 启动时会读取 Composer 的 vendor/composer/autoload_psr4.php，同时自身也有注解扫描缓存。调试时需清空两层：
- Composer 缓存：
composer dump-autoload -o（强制重生成） - Hyperf 运行时缓存：
php bin/hyperf.php clear:all或手动删掉runtime/container和runtime/cache - 验证是否加载成功：运行
composer show --platform | grep autoload查看当前 autoload 机制；也可临时在bin/hyperf.php开头加var_dump(class_exists('App\Controller\UserController'));直接测试
启用 Hyperf 的调试模式并查看日志细节
在 .env 中设置：APP_ENV=dev<br>DEBUG=true
然后启动服务时加上详细日志输出：php bin/hyperf.php start --verbose
观察控制台是否出现类似 Scan class AppControllerUserController 的提示。如果没有，说明注解扫描或自动加载根本未触达该类——此时回到前几步重点检查路径与命名空间。
