Yii自动加载分三步：先查Yii::$classMap映射表（O(1)速查），再按命名空间+别名规则生成路径（如appcontrollersSiteController→@app/controllers/SiteController.php），最后fallback；纯类名如MyHelper不走后两步，须进$classMap或由Composer管理。
Yii 的自动加载不是“魔法”，它靠的是 spl_autoload_register() 注册的明确函数调用顺序和三层查找逻辑。你遇到类找不到、别名解析失败、或自定义类不生效，基本都卡在这三层里某一处。
Yii::autoload() 是怎么被触发的？
PHP 在实例化一个尚未 require 过的类时（比如 new appcontrollersSiteController()），会依次调用所有已注册的 autoload 函数。Yii 把自己的 Yii::autoload() 放在了最前面——这靠的是入口文件 index.php 中 require Yii.php 必须写在 vendor/autoload.php 之后。
关键点：
-
spl_autoload_register(['Yii', 'autoload'], true, true)的第三个参数true表示“prepend”，即插到栈顶； - 如果把
Yii.php提前引入，它的 autoloader 就可能被 Composer 的覆盖，导致自定义命名空间失效； - 一旦某个 autoload 函数成功
include了文件，PHP 就不再调用后续 autoload 函数——所以 Yii 的优先级必须最高。
类文件路径怎么算出来的？
Yii 不是靠遍历目录猜路径，而是用确定性算法把类名转成带别名的路径：
@' . str_replace('\', '/', $className) . '.php'
比如 appmodelsUser → @app/models/User.php → 再通过 Yii::getAlias('@app') 解析为真实磁盘路径（如 /var/www/myapp/frontend）。
注意几个硬性条件：
- 类名必须含反斜杠（
），纯全局类名如MyHelper不走这套逻辑，只能进Yii::$classMap或靠 Composer； - 别名必须已定义，否则
getAlias()返回原字符串，include会失败； - 路径中不能有大小写混用问题：Windows 下可能“看起来”能加载，Linux 下直接报
Class not found。
为什么有些类秒加载，有些却慢或失败？
因为 Yii 查找类分三步，且每步都可能短路：
- 先查
Yii::$classMap—— 这是静态数组，O(1) 查找。所有核心类（如yiiwebController）都在vendor/yiisoft/yii2/classes.php里预埋好了映射； - 再按命名空间 + 别名规则生成路径并尝试
include； - 最后 fallback 到 PHP 的
include_path（几乎不用，也不建议依赖）。
常见掉坑场景：
- 手动加了
Yii::$classMap['myUtil'] = '@common/utils/Util.php';，但没在应用启动早期执行（比如放在 controller 里），那就白写了； - 改了别名（如重定义
@app），但没清 OPCache，旧路径还在缓存里； - 用了 PSR-4 兼容写法，但目录结构和命名空间对不上，比如
common/models/User.php声明了namespace frontendmodels;—— 别名解析会去@frontend/models/User.php找，当然找不到。
自定义类不生效？先确认这三件事
这不是配置问题，是路径、命名、时机三个刚性约束同时满足才能 work：
- 类文件必须在别名指向的目录下，且子路径严格匹配命名空间层级（
appservicesPaymentService→@app/services/PaymentService.php）； - 命名空间开头不能漏
app（或frontend、backend），也不能多写一层（比如appppmodelsUser）； - 别名定义必须早于任何类使用——通常写在
common/config/aliases.php或入口脚本头部，而不是在某个组件初始化里临时加。
最常被忽略的是：别名解析本身不报错，但解析结果是错的路径，include 失败后 PHP 只抛出 “Class not found”，不会告诉你它到底试了哪几个路径。调试时可临时在 Yii::autoload() 里加日志，看 $classFile 算出来是什么。
