controllerMap用于重映射控制器ID到任意类，发生在路由解析后、控制器实例化前，仅替换目标类而不改变路由规则或URL生成逻辑。
controllerMap 是用来重映射控制器 ID 到任意类的配置项
它不改变路由规则，也不影响 URL 解析逻辑，只在路由解析出 controller ID 后、实例化控制器前，做一次“替换跳转”。比如请求 /index.php?r=account/profile，Yii 原本会尝试加载 app\controllers\AccountController，但如果你在 controllerMap 里写了 'account' => 'app\controllers\UserController'，那最终执行的就是 UserController::actionProfile()。
这种映射发生在框架内部的 createController() 流程中，属于运行时行为，不依赖别名或自动加载顺序 —— 只要目标类能被正常加载（即路径存在、命名空间正确、文件可读），就能生效。
什么时候必须用 controllerMap 而不是改路由或移动类
常见于以下场景：
- 已有线上 URL（如
/api/v1/user）不能变，但后端想把逻辑从ApiController拆到Api\UserController，又不想动 Nginx 或urlManager规则 - 多个模块共用同一套控制器逻辑（比如前后台都用
admin\user\IndexAction），但又不想复制代码或搞继承污染 - 临时灰度切换：把
payment映射到新写的PaymentV2Controller，上线验证没问题再切回默认 - 第三方 SDK 提供的控制器类不在标准命名空间下（如
vendor\some\pkg\LegacyController），无法靠controllerNamespace自动发现
controllerMap 配置写错的典型表现
不是 404，也不是白屏，而是报错信息直指类加载失败，例如：
Invalid Configuration – yii\base\InvalidConfigExceptionFailed to instantiate component or class "app\controllers\MissingController".
原因往往有这几个：
- 类名拼写错误，比如写成
'account' => 'app\controller\UserController'（少了个s） - 目标类文件不存在，或路径没按命名空间严格对应（
app\controllers\UserController必须在@app/controllers/UserController.php） - 用了数组形式配置但漏了
class键：'article' => ['enableCsrfValidation' => false]会直接报错，必须写成'article' => ['class' => 'app\controllers\PostController', 'enableCsrfValidation' => false] - 在 console 应用里配了 web 专用控制器（如继承自
yii\web\Controller），而当前是yii\console\Application实例 —— 控制器类和应用类型不匹配
controllerMap 和 controllerNamespace 的关系容易被混淆
controllerNamespace 是全局“默认查找路径”，决定 site → app\controllers\SiteController 这种隐式映射；而 controllerMap 是显式覆盖，优先级更高 —— 只要命中 key，就跳过 controllerNamespace 查找逻辑。
也就是说，即使你把 controllerNamespace 改成 'frontend\controllers'，只要 controllerMap 里有 'admin' => 'backend\controllers\AdminController'，/admin/index 就永远走 backend\controllers\AdminController，跟 controllerNamespace 无关。
真正容易被忽略的是：controllerMap 不参与路由生成。调用 Url::to(['account/profile']) 时，生成的仍是 /index.php?r=account/profile，而不是转向 user/profile —— 它只管“进来的请求往哪跑”，不管“出去的链接怎么写”。
