controllerMap是Yii2中将URL路径前缀硬绑定到指定Controller类的映射机制，不参与路由解析，仅在Module或Application配置中生效，优先级高于默认控制器发现但低于urlManager.rules。
控制器映射不是路由，是 URL 到 Controller 类的硬匹配规则
Yii2 的 controllerMap 本质是模块（Module）或应用（Application）级的“别名路由表”，它不参与 URL 解析，也不走路由规则匹配；而是直接把某个 URL 路径前缀，强制绑定到指定的 Controller 类。比如配置 'get-server-addr' => 'app\controllers\GetServerAddrController'，那么访问 /get-server-addr/index 就会跳过默认的驼峰转横线逻辑，直通该类。
常见错误现象：404 报错但控制器文件明明存在、命名也正确——往往是因为没意识到 Yii2 默认只支持 kebab-case 映射（如 user-profile → UserProfileController），而你写了 getUserInfo 却试图用 /getUserInfo 访问，这根本不会进 controllerMap，连匹配机会都没有。
- 只在
Module或Application配置中生效，不能写在控制器里 - 键名是 URL 中的路径段（不含斜杠），值是完整类名（带命名空间）或别名路径（如
@app/controllers/XXX） - 优先级高于默认控制器发现机制，但低于 URL 规则（
urlManager.rules）
Yii::$classMap 和 controllerMap 完全不是一回事
很多人混淆这两个 Map：前者是 PHP 类自动加载的“快捷通道”，用于绕过 PSR-4 扫描，提升性能；后者是 MVC 层的控制器分发开关。比如你引入一个第三方 SDK 类 CryptAES，想让它随处可用，就该往 Yii::$classMap 里加映射；而你想把 /api/v1/pay 指向一个非标准命名的控制器，才用 controllerMap。
使用场景差异明显：Yii::$classMap 在应用启动时一次性注册，影响所有请求；controllerMap 只在 URL 解析阶段起作用，且仅对匹配的路径生效。
-
Yii::$classMap['CryptAES'] = __DIR__ . '/../vendor/CryptAES.php';—— 加载类文件 -
'controllerMap' => ['pay' => 'common\controllers\PayGatewayController']—— 分发请求 - 混用会导致类找不到（
Class 'PayGatewayController' not found）或路由失效（404）
驼峰控制器名必须转横线？不一定，但改法有代价
默认行为确实强制 GetServerAddrController 只能通过 /get-server-addr 访问，源码在 vendor/yiisoft/yii2/base/Controller.php 的 id 属性生成逻辑里写死。你可以改，但不建议全局动——尤其在 advanced 模板多 module 共存时。
更稳妥的做法是：对个别需要“保持原方法名即 URL”的控制器，用 controllerMap 显式绑定，而不是重写核心逻辑或 patch 框架源码。
- 在
frontend/config/main.php的modules配置里加：'controllerMap' => ['get-server-addr' => 'frontend\controllers\GetServerAddrController'] - 确保该控制器内定义了
public $defaultAction = 'index';，否则/get-server-addr仍会 404 - 别试图用
urlManager.rules做相同事——它只能重写路径，无法改变控制器类的解析过程
第三方类库手动引入时，Yii::$classMap 是最轻量可靠的方案
比起 include_once 或在 index.php 里硬 require，Yii::$classMap 是框架原生支持的类加载兜底机制，既不破坏 autoloader 流程，又避免重复加载风险。它适合单文件类、无命名空间的老 SDK、或未遵循 PSR 标准的私有工具类。
容易踩的坑：路径写错（漏 .php）、类名大小写不一致（Windows 不敏感，Linux 直接报错）、映射后仍用 new CryptAES() 却忘了加 \（应为 new \CryptAES()）。
- 配置位置：推荐统一写在
config/bootstrap.php或web.php开头，确保早于任何类使用 - 验证是否生效：在任意 action 里 var_dump(class_exists('CryptAES')) —— 应返回 true
- 复杂类库（含依赖、子类、trait）慎用 classMap，优先走 Composer autoload
复杂点在于：controllerMap 和 Yii::$classMap 看似都是“映射”，但一个管运行时分发，一个管启动时加载，层级不同、时机不同、出错表现也不同。调试时得先分清是“找不到控制器”还是“找不到类”，再决定查哪张表。
