Yii 2.0 以 別名 系統統一管理路徑與 URL，避免硬編碼絕對路徑。框架啟動時自動註冊 12 個核心別名 (11 路徑 + 1 URL)，擴展透過 Composer 自動註冊二級別名。本文逐項解析各別名指向、典型使用場景、動態解析方法與擴展別名註冊機制。
| 別名 | 類型 | 指向路徑/URL | 典型值範例 | 使用場景 |
|---|---|---|---|---|
@yii | 路徑 | 框架核心目錄 (含 BaseYii.php) | /vendor/yiisoft/yii2 | 引用框架內部類、預設配置 |
@app | 路徑 | 當前應用根目錄 (入口腳本所在專案根目錄) | /var/www/myapp (basic)/var/www/myapp/frontend (advanced) | 所有業務代碼相對路徑基準 |
@vendor | 路徑 | Composer vendor 目錄 | @app/vendor 或 @app/../vendor | 第三方庫路徑、Yii::getAlias('@vendor/foo/bar') |
@bower | 路徑 | Bower 套件目錄 | @vendor/bower | 前端舊套件 (已棄用，建議遷移 npm) |
@npm | 路徑 | NPM 套件目錄 (via fxp/composer-asset-plugin) | @vendor/npm | 前端套件來源，配合 AssetBundle |
@runtime | 路徑 | 運行時緩存/日誌/會話目錄 | @app/runtime | 寫入臨時檔、日誌、快取 |
@webroot | 路徑 | Web 入口目錄 (含 index.php) | @app/web (basic/advanced frontend) | 公開資源根目錄、上傳檔案存放 |
@web | URL | 應用根 URL (含 scheme/host/path) | https://example.com 或 /frontend/web | 生成完整連結、AJAX 請求 URL、資源引用 |
@common | 路徑 | Advanced 模板共用代碼目錄 | /var/www/myapp/common | 跨前後台共用 Model/Component |
@frontend | 路徑 | 前台應用目錄 | /var/www/myapp/frontend | 前台專用 Controller/View/Config |
@backend | 路徑 | 後台應用目錄 | /var/www/myapp/backend | 後台專用 Controller/View/Config |
@console | 路徑 | 命令列應用目錄 | /var/www/myapp/console | Migration、Cron、Queue Worker |
<?php
// 1. 解析為實際路徑/URL
$path = Yii::getAlias('@runtime/logs/app.log'); // → /var/www/myapp/runtime/logs/app.log
$url = Yii::getAlias('@web/images/logo.png'); // → https://example.com/images/logo.png
// 2. 檢查別名是否存在
if (Yii::getAlias('@npm/jquery', false) !== false) { ... }
// 3. 在配置檔中使用 (main.php)
'components' => [
'cache' => [
'class' => 'yii\caching\FileCache',
'cachePath' => '@runtime/cache', // 自動解析
],
'view' => [
'theme' => [
'pathMap' => ['@app/views' => '@app/themes/basic/views'],
],
],
],
// 4. AssetBundle 中引用
class MyAsset extends AssetBundle {
public $sourcePath = '@bower/jquery/dist'; // 或 @npm/jquery/dist
public $js = ['jquery.min.js'];
}
// 5. 控制器/視圖快捷用法
$this->registerJsFile(Yii::getAlias('@web') . '/js/app.js');
?>
Composer 安裝擴展時，若 composer.json 含 extra.asset-aliases 或 extra.yii-aliases，框架啟動會自動註冊：
// vendor/yiisoft/yii2-jui/composer.json 片段
"extra": {
"yii-aliases": {
"@yii/jui": ""
}
}
// 安裝後可直接用 @yii/jui 指向該擴展根目錄
<?php
// config/bootstrap.php 或 common/config/bootstrap.php
Yii::setAlias('@storage', '/mnt/nfs/storage');
Yii::setAlias('@cdn', 'https://cdn.example.com');
// 甚至可覆蓋核心別名 (謹慎)
Yii::setAlias('@runtime', '/tmp/yii-runtime-' . getmypid());
@runtime、@webroot/uploads 掛載宿主機目錄，容器重建不丟資料@webroot/uploads 映射至 S3/OSS 掛載點，或自定義 @storage 指向雲端 SDK 封裝@app 下不同 @frontend/@backend 共享 @common，配置差異化
