Laravel Excel 教學：從入門到精通，完整匯入匯出實戰與進階技巧

Laravel Excel 是什麼？適用情境與優勢

Laravel Excel 是一套專為 Laravel 框架設計的 Excel 檔案處理套件，基於 PhpSpreadsheet，讓開發者能以簡潔的語法實現 Excel 檔案的匯入、匯出、格式化與資料驗證。相較於直接使用 PhpSpreadsheet，Laravel Excel 提供更貼合 Laravel 生態的 API，支援 Artisan 指令、依賴注入、Queue 批次處理等功能，適合需要批量資料處理、報表產生、名單匯入等需求的專案。

主要優勢：
– 介面簡潔，易於整合至現有 Laravel 專案
– 支援 xlsx、xls、csv 等多種格式
– 內建資料驗證、格式化、事件監聽等進階功能
– 適合用於用戶資料匯入、財務報表匯出、批次資料維護等情境

與 PhpSpreadsheet 差異：
Laravel Excel 以 Laravel 服務提供者、Facades、事件等方式包裝 PhpSpreadsheet，讓 Laravel 開發者能以熟悉的方式操作 Excel 檔案，並簡化常見流程。

安裝與基本設定

安裝 Laravel Excel

在專案根目錄下，使用 Composer 安裝 Laravel Excel 套件：

composer require maatwebsite/excel

Laravel Excel 支援 Laravel 5.8 以上版本，建議使用最新版以獲得最佳相容性與功能。

服務提供者註冊

• Laravel 5.5 以上：自動註冊，無需手動設定。
• Laravel 5.4 以下：需在 config/app.php 的 providers 陣列中加入：

Maatwebsite\Excel\ExcelServiceProvider::class,

發佈與調整設定檔

如需自訂設定，可發佈設定檔：

php artisan vendor:publish --provider="Maatwebsite\Excel\ExcelServiceProvider"

此指令會產生 config/excel.php，可調整預設匯入/匯出格式、記憶體限制、Queue 設定等。

Excel 檔案匯入教學

建立 Import Class

使用 Artisan 指令建立匯入類別：

php artisan make:import UsersImport --model=User

此類別將用於解析 Excel 檔案並將資料寫入資料庫。

撰寫資料匯入邏輯

在 app/Imports/UsersImport.php 中，實作 ToModel 介面，範例如下：

namespace App\Imports;

use App\Models\User;
use Maatwebsite\Excel\Concerns\ToModel;

class UsersImport implements ToModel
{
    public function model(array $row)
    {
        // 資料驗證與轉換
        if (!filter_var($row[1], FILTER_VALIDATE_EMAIL)) {
            return null; // 跳過不合法資料
        }

        return new User([
            'name'  => $row[0],
            'email' => $row[1],
        ]);
    }
}

進階應用：資料驗證與過濾
可實作 WithValidation 介面，進行欄位驗證，並回報錯誤訊息。

控制器實作

於控制器中處理檔案上傳與匯入：

use App\Imports\UsersImport;
use Maatwebsite\Excel\Facades\Excel;

public function import(Request $request)
{
    $request->validate([
        'file' => 'required|file|mimes:xlsx,csv,xls'
    ]);

    try {
        Excel::import(new UsersImport, $request->file('file'));
        return back()->with('success', '匯入成功');
    } catch (\Exception $e) {
        return back()->withErrors(['file' => '匯入失敗：' . $e->getMessage()]);
    }
}

進階匯入技巧

• 批次處理大型檔案：實作 WithBatchInserts、WithChunkReading 介面，提升效能，避免記憶體溢出。
• 跳過不合法資料：於 model() 回傳 null 或拋出例外，並在前端回報錯誤。
• 資料前處理：可於 Import Class 加入資料清洗、格式轉換邏輯。

實務案例：用戶名單批次匯入
某企業需將人資系統匯出的 Excel 員工名單批次導入系統，透過 Laravel Excel 可自動驗證信箱格式、去除重複資料，並於錯誤時回報詳細行數，提升作業效率。

Excel 檔案匯出教學

建立 Export Class

使用 Artisan 指令建立匯出類別：

php artisan make:export UsersExport --model=User

撰寫資料匯出邏輯

於 app/Exports/UsersExport.php 中實作 FromCollection 介面：

namespace App\Exports;

use App\Models\User;
use Maatwebsite\Excel\Concerns\FromCollection;

class UsersExport implements FromCollection
{
    public function collection()
    {
        // 可加條件篩選
        return User::select('name', 'email')->where('active', 1)->get();
    }
}

進階應用：自訂欄位、格式化
可實作 WithHeadings、WithMapping、WithStyles 介面，自訂表頭、資料格式與樣式。

控制器實作

於控制器中觸發匯出：

use App\Exports\UsersExport;
use Maatwebsite\Excel\Facades\Excel;

public function export()
{
    return Excel::download(new UsersExport, 'users.xlsx');
}

• 可自訂檔名、檔案格式（xlsx、csv等）

進階匯出技巧

• 多 sheet 匯出：實作 WithMultipleSheets 介面，產生多個工作表。
• 自訂格式與樣式：設定欄寬、字型、顏色、合併儲存格等。
• 大量資料分批匯出：搭配 Queue，避免逾時與記憶體溢位。

實務案例：年度報表自動產生
財務部門每月需產生多份報表，透過 Laravel Excel 可自動分 sheet 匯出不同部門資料，並加總統計，減少人工 Excel 編輯時間。

常見問題與除錯

Q1：匯入時出現「資料格式錯誤」怎麼辦？
A：請確認 Excel 欄位順序、型別正確，可於 Import Class 加入驗證並回報錯誤行。

Q2：匯出檔案打不開或損壞？
A：檢查資料有無特殊字元、過長內容，並確認匯出格式與副檔名一致。

Q3：如何提升大量資料匯入/匯出效能？
A：建議使用 WithChunkReading、WithBatchInserts 介面，並搭配 Queue 非同步處理。

Q4：支援哪些檔案格式？
A：支援 xlsx、xls、csv，部分功能依格式略有差異。

Q5：如何只匯出部分欄位？
A：於 Export Class 的查詢中指定欄位，或於 map() 方法自訂輸出內容。

實務案例分享

情境一：用戶名單批次匯入
某 SaaS 平台需定期將客戶名單從 Excel 匯入系統，利用 Laravel Excel 可自動驗證信箱、去除重複，並於錯誤時回報詳細行數，提升作業效率。

情境二：多部門報表自動匯出
企業每月需產生多份部門報表，透過多 sheet 匯出與自訂格式功能，能自動產生合併儲存格、加總統計，減少人工編輯時間。

情境三：PDF 文件自動產生與簽核
若需將 Excel 匯出後自動轉為 PDF 並進行線上簽核，可搭配 pdfFiller 或 SignNow 等工具，實現完整數位流程。

安全性與最佳實踐

• 檔案權限：上傳檔案應限制存取權限，避免未授權下載。
• 資料驗證：匯入時務必驗證資料格式，避免異常資料寫入資料庫。
• 資安建議：避免將敏感資料明文存放於 Excel，匯出時可加密或設定存取密碼。
• 效能優化：大量資料建議分批處理，避免伺服器資源耗盡。

與其他工具比較

補充說明：
若專案需與雲端協作、多人同時編輯，可考慮 Google Sheets API；若需進行 PDF 轉換或線上簽核，則可搭配 pdfFiller、SignNow 等工具。

結論與延伸學習建議

Laravel Excel 讓 Laravel 專案能輕鬆處理 Excel 檔案的匯入與匯出，無論是批次名單導入、報表產生、資料驗證等皆能高效實現。建議深入閱讀 Laravel Excel 官方文件，並依實際需求善用進階功能，如 Queue 處理、多 sheet、資料驗證等，提升專案管理與團隊協作效率。若有進一步的檔案處理、雲端協作或 PDF 簽核需求，也可評估 pdfFiller、SignNow 等工具，打造完整數位化流程。