Hyperf控制器默认存放在app/Controller目录,由ApplicationFactory初始化时的'app_path'参数决定;需严格匹配命名空间、类名及PSR-4自动加载规则,否则导致类找不到。

app/Controller 是 Hyperf 控制器文件的默认存放路径。
这个路径不是硬编码进框架的,而是由 ApplicationFactory::create() 初始化时传入的 'app_path' 参数决定的。Hyperf 默认把 app_path 设为 BASE_PATH . '/app',所以控制器自然落在 app/Controller 子目录下。
实际开发中要注意几个关键点:
控制器命名和命名空间必须严格匹配目录结构
-
app/Controller/IndexController.php的类必须声明为namespace App\Controller; - 类名必须是
IndexController,且继承AbstractController(或直接用注解,如@Controller) - 如果放错目录(比如丢到
app/Http/Controller),即使命名空间写对,ClassLoader也找不到——因为 PSR-4 自动加载规则只认app/下的Controller、Service等标准子目录
别手动改 app_path,除非你重写了整个加载逻辑
- 在
public/index.php里能看到'app_path' => BASE_PATH . '/app'这行,不建议修改它 - 如果真要换位置(比如想用
src/Controller),得同步改composer.json的autoload.psr-4,并确保ConfigProvider和路由解析能对上——容易引发Class not found或注解扫描失败
生成命令默认也往这儿写
-
php bin/hyperf gen:controller FooController会直接创建app/Controller/FooController.php - 模板路径(
config/autoload/generate.php中的'path')若没显式配置,就 fallback 到这个默认值
\ 或 /:路径分隔符交给 DIRECTORY_SEPARATOR 或 Hyperf\Utils\Str::of() 处理,app/Controller 这种写法本身是安全的——框架内部会自动标准化。
真正容易出问题的不是“放哪儿”,而是放对了却忘了命名空间、或者改了目录但没同步更新 PSR-4 配置。


















