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

# Laravel Maestro — 啟動套件開發的協調器

> 調查 Laravel 官方新儲存庫「Maestro」。解說如何在一個 monorepo 內管理多個啟動套件變體，並有效率地接受貢獻的協調器機制。

<Info>
  本文根據原始碼調查整理。目前尚無官方文件，仍為正式發佈前的儲存庫（2026 年 4 月時點）。
</Info>

## 什麼是 Maestro

[Laravel Maestro](https://github.com/laravel/maestro) 是集中管理 Laravel [啟動套件](https://laravel.com/starter-kits)群的 monorepo 型協調器。

Laravel 啟動套件涵蓋 React、Vue、Svelte（Inertia）與 Livewire 等多個技術堆疊，再加上各堆疊的認證方式（Fortify、WorkOS）與選項（Teams、Blank）的組合，共有超過 15 種變體。Maestro 以單一儲存庫管理這些變體，並提供將變更自動反映到各啟動套件儲存庫的機制。

```mermaid theme={null}
graph TD
    A["laravel/maestro<br>（monorepo）"] --> B["orchestrator/<br>建置工具"]
    A --> C["kits/<br>原始碼檔案"]
    A --> D["browser_tests/<br>瀏覽器測試"]
    B --> E["以 build 指令<br>組合變體"]
    E --> F["build/<br>已建置的套件"]
    F --> G["以 composer kit:run<br>啟動與 watch"]
    G --> H["變更自動反映<br>到 kits/"]
```

## 解決什麼問題

當啟動套件分成多個變體時，把單一修正反映到所有變體會變得繁瑣。例如把認證表單的驗證修改分別針對 React、Vue、Svelte、Livewire 各發一個 PR 就很沒效率。

Maestro 用「共用層與變體層階層結構」解決此問題。變更該加在哪一層由協調器判斷，並自動套用到最合適的位置。

## 啟動套件的變體

Maestro 管理的啟動套件由兩個技術堆疊組成。

### Livewire 堆疊（6 個變體）

| 變體                              | 說明                      |
| ------------------------------- | ----------------------- |
| Blank                           | 無認證的最小結構                |
| Fortify                         | 由 Laravel Fortify 提供的認證 |
| Fortify (Multi-file Components) | 將 Blade view 拆到元件檔的結構   |
| Fortify (Teams)                 | Fortify 認證 + Teams 支援   |
| WorkOS                          | 由 WorkOS 提供的認證          |
| WorkOS (Teams)                  | WorkOS 認證 + Teams 支援    |

### Inertia 堆疊（15 個變體）

React、Vue、Svelte 三個框架 × Blank、Fortify、WorkOS × 有無 Teams 的組合，共 15 個變體。

## 儲存庫結構

```
laravel/maestro/
├── orchestrator/    # 管理建置的 Laravel 應用
│   ├── app/Console/Commands/BuildCommand.php
│   ├── app/Enums/StarterKit.php
│   └── scripts/
├── kits/            # 啟動套件的原始碼
│   ├── Shared/      # 所有變體共用檔案
│   ├── Livewire/    # Livewire 專屬檔案
│   └── Inertia/     # Inertia 專屬檔案（React/Vue/Svelte）
└── browser_tests/   # 瀏覽器測試
    ├── bootstrap/
    ├── common/
    └── teams/
```

`orchestrator` 目錄本身就是一個 Laravel 應用，管理啟動套件的建置與執行。

## 檔案階層系統

Maestro 的核心是「以層疊方式組合啟動套件」的機制。以 Livewire（Fortify）為例，會依以下順序複製檔案，後層覆寫前層。

```mermaid theme={null}
graph LR
    A["Shared/Blank<br>共用 Blank"] --> B["Livewire/Blank<br>Livewire 最小結構"]
    B --> C["Shared/Base<br>共用 Base"]
    C --> D["Livewire/Base<br>Livewire Base"]
    D --> E["Shared/Fortify<br>共用 Fortify"]
    E --> F["Livewire/Fortify<br>Livewire Fortify"]
    F --> G["build/<br>完成的套件"]
```

有了這樣的階層，「共用修正加在 `Shared/`、Livewire 專屬修正加在 `Livewire/`」的規則就變得清楚明確。

## 貢獻流程

要對啟動套件貢獻，並非到個別啟動套件的儲存庫，而是在此 Maestro 儲存庫進行。

<Steps>
  <Step title="切換到 orchestrator 目錄並建置套件">
    ```bash theme={null}
    cd orchestrator
    php artisan build
    ```

    可透過互動式 prompt 選擇目標套件與認證變體，也能用 flag 直接指定。

    ```bash theme={null}
    php artisan build --kit=vue
    php artisan build --kit=react --workos
    php artisan build --kit=livewire --teams
    php artisan build --kit=vue --workos --teams
    ```
  </Step>

  <Step title="啟動已建置套件">
    ```bash theme={null}
    composer kit:run
    ```

    Laravel 開發伺服器與檔案 watcher 會一起啟動。在 `build/` 目錄的變更會自動複製回 `kits/` 的適當位置。
  </Step>

  <Step title="修改並測試">
    編輯 `build/` 目錄內的檔案。watcher 會偵測變更，自動反映到 `kits/` 目錄。
  </Step>

  <Step title="建立 PR">
    對 `kits/` 目錄的變更做 commit 並開 PR。合併後 Maestro 會自動將變更推送到各啟動套件儲存庫。
  </Step>
</Steps>

<Warning>
  `build/` 目錄在 gitignore 中。所有變更請於 `build/` 內進行，讓 watcher 同步到 `kits/` 後再 commit。
</Warning>

## 其他開發指令

### Lint

```bash theme={null}
# 對 kits 與 browser_tests 執行 Pint（僅 PHP）
composer kits:pint

# PHP lint + 各 Inertia 變體的前端 lint
composer kits:lint

# 只針對特定框架
composer kits:lint -- --vue
composer kits:lint -- --react --svelte
```

### 瀏覽器測試

```bash theme={null}
# 執行所有變體的瀏覽器測試
composer kits:browser-tests

# 限定特定框架、變體
composer kits:browser-tests -- --vue
composer kits:browser-tests -- --livewire --fortify
```

瀏覽器測試以 Pest + Playwright 執行。`browser_tests/` 目錄下以 `bootstrap/`（共用設定）、`common/`（Fortify 用）、`teams/`（Teams 用）三層結構整理測試。

### 用 flag 篩選

各指令可組合 `--livewire`、`--react`、`--svelte`、`--vue` 與 `--blank`、`--fortify`、`--workos`、`--teams` flag 來篩選對象。

```bash theme={null}
# 只檢查 Vue 與 Svelte 的 Fortify 變體
composer kits:check -- --vue --svelte --fortify

# 只限所有框架的 WorkOS 變體
composer kits:check -- --workos
```

## 設定 WorkOS 環境變數

要建置並執行 WorkOS 變體時，於 `orchestrator/.env` 設定 WorkOS 的 client ID 與 API key。建置時這些值會被複製到 `build/` 目錄的 `.env`。

```bash theme={null}
# orchestrator/.env
WORKOS_CLIENT_ID=your_client_id
WORKOS_API_KEY=your_api_key
```

## 目前開發狀況

* **GitHub 儲存庫**：[laravel/maestro](https://github.com/laravel/maestro)
* **正式發佈**：無（版本 tag 與 release 尚未公開）
* **最後提交**：2026 年 4 月（持續開發中）
* **需要 PHP 版本**：^8.2
* **Laravel 版本**：^13.0

Maestro 不是對終端使用者的套件，而是作為 Laravel 團隊與貢獻者的**開發基礎架構**。啟動套件本體（如 `laravel/starter-kit-react`）由 Maestro 從此 monorepo 產生與管理。

<Card title="laravel/maestro 儲存庫" icon="github" href="https://github.com/laravel/maestro">
  對啟動套件貢獻有興趣的人請先閱讀 Maestro 的 README。
</Card>

<Card title="Laravel 啟動套件官方文件" icon="book-open" href="https://laravel.com/docs/starter-kits">
  啟動套件本身的使用方式請參考官方文件。
</Card>


## Related topics

- [部落格](/zh-TW/blog/index.md)
- [Laravel 啟動套件的建立方式](/zh-TW/advanced/starter-kit-creation.md)
- [Laravel 套件開發](/zh-TW/advanced/package-development.md)
- [Laravel Chisel — 啟動套件的安裝後腳本函式庫](/zh-TW/blog/chisel-introduction.md)
- [以 Testbench Workbench 推進套件開發](/zh-TW/advanced/package-workbench.md)