> ## 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) 是一个 monorepo 型编排器,用来集中管理 Laravel 的[启动套件](https://laravel.com/starter-kits)们。

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>启动 & 监视"]
    G --> H["把变更自动<br>同步到 kits/"]
```

## 解决了什么问题

启动套件被拆成大量变体后,把一处修改同步到所有变体会变得非常繁琐。比如认证表单的校验修复,如果要分别向 React、Vue、Svelte、Livewire 各自提交 PR,效率非常低。

Maestro 通过“共享层与变体层的分层结构”解决了这个问题。修改应该加到哪一层,由编排器判断,并自动应用到最合适的位置。

## 启动套件的变体

Maestro 管理的启动套件由两大技术栈组成。

### Livewire 栈(6 个变体)

| 变体                              | 说明                     |
| ------------------------------- | ---------------------- |
| Blank                           | 无认证的最小配置               |
| Fortify                         | 基于 Laravel Fortify 的认证 |
| Fortify (Multi-file Components) | 把 Blade 视图分离到组件文件的配置   |
| 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
    ```

    交互式提示会引导你选择目标套件和认证变体。也可以直接用参数指定:

    ```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 开发服务器和文件监视器会同时启动。你在 `build/` 目录里做的修改会被自动同步到 `kits/` 里对应的位置。
  </Step>

  <Step title="修改并测试">
    编辑 `build/` 目录内的文件。监视器会捕获变动,并自动同步到 `kits/` 目录。
  </Step>

  <Step title="创建 PR">
    把 `kits/` 目录的变更提交并发起 PR。合并后,Maestro 会自动把变更推送到各个启动套件仓库。
  </Step>
</Steps>

<Warning>
  `build/` 目录被 gitignore 掉了。所有修改都请在 `build/` 中进行,让监视器同步到 `kits/` 后再提交。
</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)三层组织测试。

### 用参数缩小范围

每个命令都能通过 `--livewire`、`--react`、`--svelte`、`--vue` 和 `--blank`、`--fortify`、`--workos`、`--teams` 参数组合来缩小执行范围。

```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)
* **正式发布**:无(尚未打版本标签或 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/starter-kits.md)
- [Laravel Chisel — 启动套件的安装后脚本库](/zh/blog/chisel-introduction.md)
- [Laravel 11 升级到 12 指南](/zh/blog/upgrade-11-to-12.md)
- [前端](/zh/frontend.md)
- [使用 Inertia.js 构建 SPA](/zh/blog/inertia-introduction.md)