Yii别名是路径解析与类加载的底层枢纽，必须以@开头，需显式调用Yii::getAlias()解析；未正确定义@php、@common等基础别名将导致自动加载、视图渲染等静默失败。
Yii 的别名不是语法糖，而是路径解析和类加载的底层枢纽——没配对或配错 @app、@common 这类基础别名，后续 include_once、自动加载、视图渲染全都会 silently 失败。
别名必须以 @ 开头，且只能在 Yii::getAlias() 里解析
直接写 '@app/config/params.php' 是字符串，不会自动展开；必须显式调用 Yii::getAlias() 才能转成真实路径。常见错误是漏掉这一步：
-
include '@app/config/params.php';→ 报错：No such file（PHP 尝试加载字面量路径） -
include Yii::getAlias('@app/config/params.php');→ 正确 - 别名里不带
@前缀，比如Yii::getAlias('app')，结果就是原样返回'app'，不会补前缀 - 别名定义时若值末尾带斜杠（如
dirname(__DIR__) . '/'），getAlias()返回的路径也会多一个斜杠，可能影响file_exists()判断
aliases 配置项必须和 components 同级，不能塞进 components 里
在 web.php 或 main.php 中写别名，必须放在配置数组顶层，和 'components' 并列。放错位置会导致别名完全不生效：
- ✅ 正确位置：
'aliases' => ['@foo' => '/path/to'], 'components' => [...] - ❌ 错误写法：
'components' => ['aliases' => [...], ...]—— Yii 忽略该配置 - 别名值建议用
dirname(__DIR__)而非__DIR__，避免指向当前 config 文件所在目录而非项目根目录 - 多个环境（dev/test/prod）共用同一份别名定义时，确保
bootstrap.php被所有入口文件加载，否则别名只在部分请求中可用
类自动加载依赖别名拼接，命名空间必须匹配别名结构
Yii 2 自动加载器看到 app\controllers\SiteController，会尝试拼出 @app/controllers/SiteController.php，再用 getAlias() 解析。这意味着：
- 如果
@app没定义，或指向了错误目录，类就找不到，报Class not found - 别名路径必须是目录，不能是具体文件（如
@app => '/path/to/index.php'会失败） - 子别名可继承父别名：定义了
@app，就能直接用@app/models/User.php，无需单独定义@app/models - 别名不支持通配符或正则，
@app/*/Service.php这种写法无效
别名值里的相对路径要小心 ../ 回溯层级
别名值中若含 ../，实际解析结果取决于运行时工作目录（CWD），不是文件所在目录。这在 CLI 和 Web 请求中行为可能不一致：
- 推荐写法：
Yii::setAlias('@common', dirname(dirname(__DIR__)) . '/common'); - 危险写法：
Yii::setAlias('@common', '../common');—— 若从yii migrate运行，CWD 是项目根，没问题；但从php yii serve启动，CWD 可能是frontend/web，导致回溯错层 -
Yii::getAlias()对不存在的别名返回原字符串（如Yii::getAlias('@missing')返回'@missing'），不会抛异常，容易掩盖配置遗漏 - 调试时可临时加一行
var_dump(Yii::getAlias('@app'));确认是否解析成功，比看报错更直接
别名机制本身轻量，但一旦和自动加载、资源发布、模板路径耦合，错误就会被延迟暴露——最常踩的坑不是“怎么定义”，而是“在哪定义”和“谁先加载”。务必确认 bootstrap.php 在应用启动早期执行，且所有别名都在那里面统一注册。
