Yii Assets 資源發布機制詳解與模塊化實戰示例

Yii CAssetManager 將受保護目錄（protected/）下的 CSS/JS/圖片發布到 Web 可訪問的 assets/ 目錄，實現模塊/擴展資源的隔離、版本管理、衝突避免。本文解析核心原理與 Admin 模塊實戰用法。

一、Assets 核心作用

1. 安全隔離： protected/ 下文件不可直接 URL 訪問，發布後生成隨機哈希目錄（如 assets/2b31b42b/）對外公開。
2. 模塊化分發： 每個模塊/擴展擁有獨立資源目錄，發布時自動複製，避免文件名衝突。
3. 版本控制： 文件變更導致哈希目錄名改變，天然解決瀏覽器緩存失效問題。

二、基礎發布用法

$assets = Yii::getPathOfAlias('ext') . '/css'; // 源目錄
$baseUrl = Yii::app()->assetManager->publish($assets); // 發布並獲取公開 URL
Yii::app()->clientScript->registerCssFile($baseUrl . '/main.css'); // 註冊引用

三、實戰：Admin 模塊資源管理最佳實踐

1. 目錄結構

protected/
└── modules/
    └── admin/
        ├── assets/          # 私有資源目錄
        │   ├── css/screen.css
        │   ├── js/admin.js
        │   └── images/logo.png
        ├── AdminModule.php
        └── views/layouts/main.php

2. AdminModule.php 封裝 assetsUrl 屬性

class AdminModule extends CWebModule
{
    private $_assetsUrl;

    public function getAssetsUrl()
    {
        if ($this->_assetsUrl === null) {
            $this->_assetsUrl = Yii::app()->getAssetManager()->publish(
                Yii::getPathOfAlias('application.modules.admin.assets')
            );
        }
        return $this->_assetsUrl;
    }

    public function setAssetsUrl($value)
    {
        $this->_assetsUrl = $value;
    }
}

3. 布局文件引用資源

<link rel="stylesheet" type="text/css"
    href="<?php echo $this->module->assetsUrl; ?>/css/screen.css"
    rel="external nofollow" />
<script src="<?php echo $this->module->assetsUrl; ?>/js/admin.js"></script>

四、強制更新發布（開發調試必備）

$baseJsUrl = Yii::app()->getAssetManager()->publish(
    $baseJsPath,
    false,  // 不強制複製（false=只在目錄不存在時複製）
    -1,     // 無限期過期
    YII_DEBUG // 調試模式下強制更新
);

參數詳解：publish($path, $hashByName, $level, $forceCopy)

• $hashByName=false：用路徑哈希做目錄名（默認 true 用修改時間）。
• $level=-1：遞歸發布所有子目錄。
• $forceCopy=YII_DEBUG：開發環境每次請求強制同步，生產環境走緩存。

五、常見坑點避雷

• 權限問題： assets/ 目錄需 Web 服務器用戶可寫（chmod 777 或 chown www-data）。
• 路徑別名錯誤： Yii::getPathOfAlias('application.modules.admin.assets') 必須指向**目錄**，非文件。
• 生產環境緩存： 部署後首次訪問會生成哈希目錄，後續請求直接走靜態文件，性能無損耗。