如何创建 Laravel Starter Kit - Knowledge of Laravel

前言

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 发布后能立刻跟进的运营流程。
搭配阅读相关指南：结合包开发基础与包的版本兼容性管理会让设计更稳。

​前言

​Starter Kit 的制作

​初始化 Laravel 项目

​配置 composer.json 的 scripts

​用 .gitattributes 控制分发对象

​发布到 Packagist

​laravel new 命令的流程

​前端框架的选择

​版本升级维护

​应对 Laravel、PHP 版本升级

​定期更新依赖

​兼容性测试

​最佳实践

前言

Starter Kit 的制作

初始化 Laravel 项目

配置 composer.json 的 scripts

用 .gitattributes 控制分发对象

发布到 Packagist

laravel new 命令的流程

前端框架的选择

版本升级维护

应对 Laravel、PHP 版本升级

定期更新依赖

兼容性测试

最佳实践