Laravel Maestro — 启动套件开发的编排器

本文基于源代码调查整理。目前还没有官方文档,仓库也还在正式发布前(截至 2026 年 4 月)。

什么是 Maestro

Laravel Maestro 是一个 monorepo 型编排器,用来集中管理 Laravel 的启动套件们。 Laravel 的启动套件包含 React、Vue、Svelte(Inertia)和 Livewire 多套技术栈,而且每套栈还会组合出不同的认证方式(Fortify、WorkOS)和可选项(Teams、Blank),总计超过 15 种变体。Maestro 让所有这些变体在一个仓库中统一管理,并把变更自动同步到各个启动套件仓库。

解决了什么问题

启动套件被拆成大量变体后,把一处修改同步到所有变体会变得非常繁琐。比如认证表单的校验修复,如果要分别向 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)为例,文件会按下面的顺序被拷贝,后一层会覆盖前一层。得益于这种层级设计,规则也很清晰:“所有套件共用的修改放到 Shared/,Livewire 特有的修改放到 Livewire/”。

贡献流程

对启动套件的贡献不再是直接向各个启动套件仓库提交,而是在 Maestro 这个仓库里进行。

进入 orchestrator 目录并构建套件

cd orchestrator
php artisan build

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

php artisan build --kit=vue
php artisan build --kit=react --workos
php artisan build --kit=livewire --teams
php artisan build --kit=vue --workos --teams

启动构建好的套件

composer kit:run

Laravel 开发服务器和文件监视器会同时启动。你在 build/ 目录里做的修改会被自动同步到 kits/ 里对应的位置。

修改并测试

编辑 build/ 目录内的文件。监视器会捕获变动,并自动同步到 kits/ 目录。

创建 PR

把 kits/ 目录的变更提交并发起 PR。合并后,Maestro 会自动把变更推送到各个启动套件仓库。

build/ 目录被 gitignore 掉了。所有修改都请在 build/ 中进行,让监视器同步到 kits/ 后再提交。

其他开发命令

Lint

# 对 kits 和 browser_tests 执行 Pint(仅 PHP)
composer kits:pint

# PHP lint + 各 Inertia 变体的前端 lint
composer kits:lint

# 只针对特定框架
composer kits:lint -- --vue
composer kits:lint -- --react --svelte

浏览器测试

# 运行所有变体的浏览器测试
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 参数组合来缩小执行范围。

# 只检查 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 文件中。

# orchestrator/.env
WORKOS_CLIENT_ID=your_client_id
WORKOS_API_KEY=your_api_key

当前开发状态

GitHub 仓库:laravel/maestro
正式发布:无(尚未打版本标签或 release)
最新提交:2026 年 4 月(积极开发中)
需要的 PHP 版本:^8.2
Laravel 版本:^13.0

Maestro 不是给终端用户的包,而是面向 Laravel 团队和贡献者的开发基础设施。启动套件本体(如 laravel/starter-kit-react)是由 Maestro 从这个 monorepo 生成并管理的。

laravel/maestro 仓库

想为启动套件做贡献,请先阅读 Maestro 的 README。

Laravel 启动套件官方文档

启动套件本身的使用方法请参考官方文档。

Changelog

Laravel 13

产品

包介绍

新仓库探索

升级指南

认证

前端

环境搭建

Laravel Maestro — 启动套件开发的编排器

什么是 Maestro

解决了什么问题

启动套件的变体

Livewire 栈(6 个变体)

Inertia 栈(15 个变体)

仓库结构

文件分层系统

贡献流程

其他开发命令

Lint

浏览器测试

用参数缩小范围

WorkOS 环境变量的设置

当前开发状态

laravel/maestro 仓库

Laravel 启动套件官方文档

​什么是 Maestro

​解决了什么问题

​启动套件的变体

​Livewire 栈(6 个变体)

​Inertia 栈(15 个变体)

​仓库结构

​文件分层系统

​贡献流程

​其他开发命令

​Lint

​浏览器测试

​用参数缩小范围

​WorkOS 环境变量的设置

​当前开发状态

laravel/maestro 仓库

Laravel 启动套件官方文档

什么是 Maestro

解决了什么问题

启动套件的变体

Livewire 栈(6 个变体)

Inertia 栈(15 个变体)

仓库结构

文件分层系统

贡献流程

其他开发命令

Lint

浏览器测试

用参数缩小范围

WorkOS 环境变量的设置

当前开发状态