Yii2控制器必须严格置于controllers/目录下，文件名格式为XXXController.php，命名空间需与路径一致，且必须use yii\web\Controller；路由ID为小写控制器名（如ProductController对应product），模块控制器须放modules/xxx/controllers/并配置$controllerNamespace。
Yii2 Controller 文件必须放在 controllers/ 目录下
不是“可以放”，而是框架硬性约定：所有继承 yii\web\Controller 的控制器类，必须位于应用根目录下的 controllers/ 子目录中，且文件名需严格匹配 XXXController.php 格式（如 SiteController.php、ProductController.php）。
常见错误现象：Invalid Route – Unable to resolve the request 或直接 404，往往是因为把控制器放到了 controllers/admin/ 却没配模块，或误丢进 models/、commands/ 甚至 views/ 里。
-
controllers/是相对应用根目录（即@app）的路径，例如@app/controllers/SiteController.php - 子目录结构可嵌套，但仅在模块（
Module）上下文中才合法。比如controllers/admin/UserController.php必须配合admin模块，且模块的$controllerNamespace要设为'app\controllers\admin' - 独立于模块的普通控制器，不能放在
controllers/的任意子目录下——否则路由解析失败，框架不会自动扫描子目录
模块内 Controller 的存放位置：modules/xxx/controllers/
如果你用了模块（比如 api 模块），控制器就不再走主 controllers/，而应放在模块自己的 controllers/ 目录下，并通过模块类的 $controllerNamespace 显式声明命名空间。
例如，app\modules\api\Module 中写了 $controllerNamespace = 'app\modules\api\controllers'，那它的控制器就必须是 modules/api/controllers/DefaultController.php，对应类名为 app\modules\api\controllers\DefaultController。
- 模块控制器的路由格式是
api/default/index（模块ID/控制器ID/动作ID），不是default/index - 别把模块控制器错放到主
controllers/下——即使类存在，路由也匹配不到，因为模块有自己的命名空间隔离 - 模块的
controllers/目录需手动创建，Gii 生成模块时不会自动建这个子目录
use yii\web\Controller 和命名空间缺一不可
光有文件位置不够，控制器类还必须满足两个语法前提：正确声明命名空间 + 正确引入父类。
比如 SiteController.php 的开头必须是：
namespace app\controllers;
use yii\web\Controller;
class SiteController extends Controller
{
public function actionIndex()
{
return $this->render('index');
}
}
- 命名空间必须与目录结构一致：
controllers/SiteController.php→app\controllers；modules/v1/controllers/UserController.php→app\modules\v1\controllers - 漏写
use yii\web\Controller会导致Class 'Controller' not found - 写成
use yii\base\Controller会报错：该类不支持render()、redirect()等 Web 特有方法
容易被忽略的关键点：路由 ID 是小写的控制器名，不是类名
控制器类叫 ProductController，它的路由 ID 就是 product，不是 Product 或 product-controller。这是大小写敏感的约定，且自动转小写。
所以访问地址是 ?r=product/index（未开启美化）或 /product/index（开启美化后），而不是 ?r=Product/index。
- 驼峰控制器名如
UserProfileController，路由 ID 是user-profile（自动用短横线分隔） - 如果在 URL 中拼错大小写（比如输成
Product），本地开发环境可能因文件系统不区分大小写“碰巧”能访问，但上线到 Linux 服务器必然 404 - IDE 自动补全有时会带出大写首字母，复制粘贴时务必手动改成小写路由
