Yii 框架文件與圖片上傳完整實戰教程

Yii 文件上傳核心流程解析

在 Yii 1.x 中實現文件上傳，核心類為 CUploadedFile。整個流程分為視圖構建表單、控制器處理上傳邏輯、模型驗證（可選）三個環節。本文通過一個完整示例演示如何上傳圖片到指定目錄。

1. 視圖層：構建上傳表單

表單必須設置 enctype="multipart/form-data"，否則文件不會被傳輸。

<form action="<?php echo $this->createUrl('/test/upload/'); ?>" method="post" enctype="multipart/form-data">
    <input type="file" name="file" />
    <input type="hidden" name="dir" value="test" />
    <input type="submit" value="Upload Image" />
</form>

2. 控制器層：處理上傳邏輯

public function actionUpload() {
    $dir = isset($_REQUEST['dir']) ? $_REQUEST['dir'] : '';
    $image = CUploadedFile::getInstanceByName('file');
    
    if ($image === null) {
        echo 'fail: 未接收到文件';
        return;
    }

    // 構建存儲路徑：webroot/images/{dir}/
    $basePath = Yii::getPathOfAlias('webroot') . '/images/' . $dir . '/';
    
    // 自動創建目錄（遞歸模式，權限 0755）
    if (!is_dir($basePath)) {
        mkdir($basePath, 0755, true);
    }

    $targetPath = $basePath . $image->name;
    
    // 保存文件，true 表示覆蓋同名文件
    if ($image->saveAs($targetPath, true)) {
        echo 'success: 文件已保存至 ' . $targetPath;
    } else {
        echo 'fail: 保存失敗，請檢查目錄寫入權限';
    }
}

3. 進階：結合模型驗證（推薦做法）

實際項目中建議使用 CFormModel 或 CActiveRecord 進行驗證，例如限制文件類型、大小：

class UploadForm extends CFormModel {
    public $file;
    public $dir;

    public function rules() {
        return array(
            array('file', 'file', 'types' => 'jpg, gif, png', 'maxSize' => 1024 * 1024 * 2, 'tooLarge' => '文件不能超過 2MB'),
            array('dir', 'safe'),
        );
    }
}

// 控制器中使用
$model = new UploadForm();
$model->attributes = $_POST['UploadForm'];
$model->file = CUploadedFile::getInstance($model, 'file');
if ($model->validate()) {
    $model->file->saveAs($targetPath);
}

常見問題排查

• 上傳失敗：檢查 php.ini 中 file_uploads = On、upload_max_filesize、post_max_size 設置。
• 權限不足：確保 Web 服務器進程（如 www-data）對目標目錄有寫入權限。
• 中文文件名亂碼：建議保存時重命名為時間戳+隨機數，或使用 iconv 轉碼。