> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Blaze 套件介紹

> 解說如何用 Livewire 官方的 Blaze 加速 Blade 元件繪製。整理 compile / memo / fold 的選擇基準、安裝方式、限制事項與內部機制。

<Info>
  本文以 [livewire/blaze](https://github.com/livewire/blaze) 的 README 為第一手資訊整理。目前 laravel.com 上尚未有 Blaze 專用文件。
</Info>

## 什麼是 Blaze

[Blaze](https://github.com/livewire/blaze) 是 Livewire 官方發佈的 Blade 元件加速套件。對象不僅限於 Livewire 元件，也包含一般的匿名 Blade 元件。

README 中匿名元件繪製 25,000 次的 benchmark 顯示從 **500ms → 13ms**（約 **97.4% 縮減**）。依情境不同也回報有 91〜97% 的縮減。

## 三種最佳化策略

Blaze 提供 `compile`（預設）、`memo`、`fold` 三種策略。

```mermaid theme={null}
flowchart LR
    A["元件呼叫"] --> B["compile<br>編譯為函式"]
    A --> C["memo<br>相同 props 記憶化"]
    A --> D["fold<br>編譯時直接生成 HTML"]
    B --> E["高相容性且大幅提升"]
    C --> F["對重複繪製效果好"]
    D --> G["最高效能但需注意"]
```

### 該選哪一個

| 策略        | 何時選用                        | 優點                | 注意事項            |
| --------- | --------------------------- | ----------------- | --------------- |
| `compile` | 最先採用的標準策略                   | 相容性高，無需設定即容易加速    | 需確認共通的限制事項      |
| `memo`    | 同一 props 反覆繪製的 icon、badge 等 | 可降低首次之後的重新繪製成本    | 帶 slot 的元件無法使用  |
| `fold`    | 用可靜態化的 UI 追求最高效能時           | 幾乎可移除執行時 overhead | 若誤用全域狀態或動態值會不一致 |

若拿不定主意，較安全的做法是**先從 `compile` 開始**，只在被找出的瓶頸處套用 `memo` / `fold`。

## 安裝與啟用

```bash theme={null}
composer require livewire/blaze:^1.0
```

啟用方式有兩種。

### 1) 對個別元件加上 `@blaze`

```blade theme={null}
@blaze

<button {{ $attributes }}>
    {{ $slot }}
</button>
```

視需要切換策略。

```blade theme={null}
@blaze(memo: true)
@blaze(fold: true)
```

### 2) 用 `Blaze::optimize()` 以目錄為單位啟用

```php theme={null}
use Livewire\Blaze\Blaze;

public function boot(): void
{
    Blaze::optimize()
        ->in(resource_path('views/components'));
}
```

啟用後清除已編譯的 view。

```bash theme={null}
php artisan view:clear
```

<Tip>
  `@blaze` 適合「先試試看」，`Blaze::optimize()` 則適合「在正式運行中大範圍套用」。README 也建議先從限定目錄開始逐步套用。
</Tip>

## 限制事項

以下是 README 中明示的限制。

* 不支援類別型元件
* 無法使用 `$component` 變數
* View composer / creator / lifecycle event 不會觸發
* 不支援 `View::share()` 變數的自動注入（若需要，請明確使用 `$__env->shared('key')`）
* 橫跨 Blade 與 Blaze 的 `@aware` 有限制（父子雙方都必須在 Blaze 側使用）
* 無法用 `view()` 直接繪製 Blaze 元件（僅能透過元件標籤）

## 與 Flux UI 的相容性

Blaze README 說明，若使用 [Flux UI](https://fluxui.dev/docs/installation)，**只要安裝 Blaze 即可零設定啟用**。

## 運作機制概要

一般 Blade 每次都會走過包含元件解析與屬性處理的繪製 pipeline。Blaze 的 `compile` 會將其編譯為最佳化過的 PHP 函式直接呼叫，大幅減少 pipeline 的 overhead。

依照 README 說明，概念上有以下差異：

* 一般：每次都執行 Blade 標準繪製流程
* Blaze `compile`：直接呼叫已編譯的函式
* Blaze `fold`：於編譯時直接嵌入 HTML，進一步減少執行時運算

`fold` 最快，但若有破壞靜態化前提的要素（認證狀態、依請求變化的值、依 session 或時間的值等）會導致問題。請鎖定高負載處，一邊確認行為一邊分階段套用。


## Related topics

- [Laravel Wayfinder 介紹](/zh-TW/blog/wayfinder-introduction.md)
- [部落格](/zh-TW/blog/index.md)
- [用 Inertia.js 建構 SPA](/zh-TW/blog/inertia-introduction.md)
- [Laravel Pennant 實務案例](/zh-TW/blog/laravel-pennant.md)
- [Laravel Telescope 實戰技巧](/zh-TW/blog/telescope-introduction.md)