如何创建 Laravel Starter Kit

前言

Starter Kit 是使用 laravel new 创建应用时通过 create-project 展开的模板项目。Laravel 13 官方 Starter Kit 有 React / Vue / Svelte / Livewire 四种，包含认证与初始 UI。你要制作自定义 Starter Kit 时做的事情也是一样的：以 Laravel 应用为基础整备后，作为 Composer 包发布即可。

官方文档：Starter Kits
官方实现示例：laravel/react-starter-kit
参考页面：Laravel Console Starter

Starter Kit 的制作

初始化 Laravel 项目

先创建作为模板的 Laravel 项目并整理不必要的示例代码。然后在 composer.json 的 name 中设置唯一的包名。

{
    "name": "example/starter-kit",
    "type": "project",
    "require": {
        "php": "^8.3",
        "laravel/framework": "^13.0"
    }
}

这个 name 之后会被 laravel new my-app --using=example/starter-kit 使用。

配置 composer.json 的 scripts

执行 laravel new 后，Starter Kit 一侧的 Composer scripts 会用于初始化流程。至少应准备 post-root-package-install 与 post-create-project-cmd。

"scripts": {
    "post-root-package-install": [
        "@php -r \"file_exists('.env') || copy('.env.example', '.env');\""
    ],
    "post-create-project-cmd": [
        "@php artisan key:generate --ansi",
        "@php -r \"file_exists('database/database.sqlite') || touch('database/database.sqlite');\"",
        "@php artisan migrate --graceful --ansi"
    ]
}

该示例参考自 laravel/react-starter-kit 的 composer.json。若你使用数据库可以直接复用。

用 .gitattributes 控制分发对象

对希望留在 Starter Kit 仓库、但不希望包含到用户生成项目中的文件，用 export-ignore 排除。

LICENSE export-ignore
composer.lock export-ignore
README.md export-ignore

详见 .gitattributes 官方示例。

发布到 Packagist

要让用户能通过 --using 使用，必须发布到 Packagist。

在 GitHub 准备公开仓库

确保 composer.json 的 name 与仓库 URL 一致后再公开。

登记到 Packagist

在 Packagist 注册仓库。发布后 example/starter-kit 就可以被解析到。

在 README 中写明使用命令

向用户提供如下引入命令。

laravel new my-app --using=example/starter-kit

laravel new 命令的流程

laravel/installer 的 NewCommand 在指定 Starter Kit 时会切换 create-project 目标并依次执行初始化命令。 NewCommand.php 中可参考的位置：

前端框架的选择

Laravel 13 官方 Starter Kit 提供 React / Vue / Svelte / Livewire，但自定义 Starter Kit 不必与该构成一致。CSS、组件库、认证方式都可以按需自由决定。

选项	主要构成	适合的场景
官方 React / Vue / Svelte / Livewire	使用 Inertia 3 或 Livewire 4 的官方构成	希望提供接近官方的开发体验
自定义前端	任意 CSS、组件库	想使用现有设计系统或其他 CSS 基础
简易 Blade Kit	以 Blade 为主，最小限度前端依赖	想以轻量构成快速引入
自定义认证 Kit	不局限于 Fortify（例如以 Socialite 为主）	想聚焦于特定认证方式

社区的 Starter Kit 常用与官方不同的 CSS 基础。认证也不必以 Fortify 为前提，请按需求设计。

版本升级维护

Starter Kit 不是「一次做完就完事」。需要随 Laravel 与 PHP 更新持续跟进。

应对 Laravel、PHP 版本升级

先更新 composer.json 的要求，然后在 CI 中确认兼容性。

"require": {
    "php": "^8.3",
    "laravel/framework": "^13.0"
}

Laravel 主版本更新时，请同时检查 laravel/framework 与相关依赖。

定期更新依赖

前端依赖变化快，按月更新任务较为稳妥。

Tailwind
组件库（shadcn/ui、shadcn-vue、shadcn-svelte、Flux UI）
Inertia / Livewire 相关包

兼容性测试

至少将以下检查纳入 CI：

composer install 成功
php artisan test 通过
npm install && npm run build 通过

最佳实践

尽早固定 name：Packagist 公开后修改成本高。
scripts 参照官方示例：破坏初始化流程会增加安装失败。
提前整备 .gitattributes：减少模板分发时的噪声。
将升级流程常态化：Laravel 发布后能立刻跟进的运营流程。
搭配阅读相关指南：结合包开发基础与包的版本兼容性管理会让设计更稳。

AI 开发

设计模式

包开发

应用结构

Laravel 13 新特性

Eloquent 深入

验证扩展

认证扩展

安全

测试

前言

Starter Kit 的制作

初始化 Laravel 项目

配置 composer.json 的 scripts

用 .gitattributes 控制分发对象

发布到 Packagist

laravel new 命令的流程

前端框架的选择

版本升级维护

应对 Laravel、PHP 版本升级

定期更新依赖

兼容性测试

最佳实践

​前言

​Starter Kit 的制作

​初始化 Laravel 项目

​配置 composer.json 的 scripts

​用 .gitattributes 控制分发对象

​发布到 Packagist

​laravel new 命令的流程

​前端框架的选择

​版本升级维护

​应对 Laravel、PHP 版本升级

​定期更新依赖

​兼容性测试

​最佳实践

前言

Starter Kit 的制作

初始化 Laravel 项目

配置 composer.json 的 scripts

用 .gitattributes 控制分发对象

发布到 Packagist

laravel new 命令的流程

前端框架的选择

版本升级维护

应对 Laravel、PHP 版本升级

定期更新依赖

兼容性测试

最佳实践