yii::setalias()必须在应用启动前调用，即new yii\web\application($config)之前；注册后不校验路径存在性，支持url或嵌套别名，但需已注册父别名且按最长前缀匹配。
Yii::setAlias() 必须在应用启动前调用
别名注册不是随时都能生效的，Yii::setAlias() 必须在 Yii 应用实例化完成前执行，否则后续 Yii::getAlias() 可能拿不到你刚设的别名。常见错误是把它写在控制器、模型或视图里——这时 Yii::$app 已存在，但别名注册逻辑早已错过时机。
正确位置是：
-
common/config/bootstrap.php（Advanced 模板） -
config/bootstrap.php或web/index.php中require __DIR__ . '/../vendor/autoload.php';之后、(new yii\web\Application($config))->run();之前
例如在 web/index.php 中：
require __DIR__ . '/../vendor/autoload.php';
require __DIR__ . '/../vendor/yiisoft/yii2/Yii.php';
// ✅ 此处注册有效
Yii::setAlias('@foo', dirname(__DIR__) . '/data');
$config = require __DIR__ . '/../config/web.php';
(new yii\web\Application($config))->run();
@ 开头、路径中不能含空格、不支持运行时变量替换
Yii::setAlias() 对输入格式很敏感：别名字符串必须以 @ 开头；路径值不能带首尾空格；且它本身不做任何变量插值 —— 即使你传入 '@app/config/{env}.php'，也不会自动替换 {env}。
常见误用包括：
- 写成
Yii::setAlias('foo', '/path')（漏了@，框架会自动补但不推荐依赖该行为） - 路径值末尾多了一个空格：
Yii::setAlias('@log', '/var/log/ ')→ 后续file_put_contents()写入失败但无明确报错 - 试图用
Yii::setAlias('@conf', '@app/config/' . $env . '.php')→$env在注册时就求值，不是每次getAlias()时动态计算
需要动态路径？先 getAlias('@app')，再拼接：sprintf('%s/config/%s.php', Yii::getAlias('@app'), $env)。
别名嵌套必须已注册，且优先匹配最长前缀
你可以用已有别名定义新别名，比如 Yii::setAlias('@foo/bar', '@app/modules/foo/bar')，但前提是 @app 已存在（它默认存在）。如果 @app 还没注册，这行代码会抛出 InvalidParamException。
匹配逻辑按「最长前缀」进行，不是「第一个匹配」：
- 注册了
Yii::setAlias('@api', '/v1')和Yii::setAlias('@api/users', '/v1/admin/users') - 调用
Yii::getAlias('@api/users/list')→ 返回/v1/admin/users/list（匹配到@api/users） - 调用
Yii::getAlias('@api/auth')→ 返回/v1/auth（只匹配到@api）
这意味着别名定义顺序无关，但层级关系必须显式注册；不能靠“推导”——@api/v2 不会自动从 @api 展开。
别名值可以是 URL、文件路径，甚至不存在的目录
Yii::setAlias() 不校验路径是否存在，也不区分文件系统路径还是 URL。你完全可以：
-
Yii::setAlias('@cdn', 'https://cdn.example.com')→ 后续在视图中<img src="<?=%20Yii::getAlias('@cdn')%20?>/logo.png"> -
Yii::setAlias('@temp', '/nonexistent/tmp')→ 只要后续代码不真去读写，就不会出错 -
Yii::setAlias('@mail', '@runtime/mail')→ 允许嵌套，只要@runtime已注册（它默认已注册）
但要注意：Yii::getAlias('@xxx') 默认抛异常，若想静默 fallback，得手动捕获：try { $path = Yii::getAlias('@xxx'); } catch (\yii\base\InvalidParamException $e) { $path = '/default'; }。
最易被忽略的一点：别名注册后不会自动同步到所有子请求或 CLI 命令中——每个入口（web/index.php、yii 命令、console/index.php）都需独立注册或通过 bootstrap 统一加载。漏掉 console 环境的别名，跑 migration 就可能报错。
