> ## 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 Starter Kit

> 讲解创建 Laravel Starter Kit、发布到 Packagist，并持续适配 Laravel 与前端版本升级的实操流程。

## 前言

Starter Kit 是使用 `laravel new` 创建应用时通过 `create-project` 展开的模板项目。Laravel 13 官方 Starter Kit 有 React / Vue / Svelte / Livewire 四种，包含认证与初始 UI。

你要制作自定义 Starter Kit 时做的事情也是一样的：以 Laravel 应用为基础整备后，作为 Composer 包发布即可。

* 官方文档：[Starter Kits](https://laravel.com/docs/starter-kits)
* 官方实现示例：[laravel/react-starter-kit](https://github.com/laravel/react-starter-kit)
* 参考页面：[Laravel Console Starter](/zh/packages/laravel-console-starter/index)

## Starter Kit 的制作

### 初始化 Laravel 项目

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

```json theme={null}
{
    "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`。

```json theme={null}
"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](https://github.com/laravel/react-starter-kit/blob/main/composer.json)。若你使用数据库可以直接复用。

### 用 .gitattributes 控制分发对象

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

```gitattributes theme={null}
LICENSE export-ignore
composer.lock export-ignore
README.md export-ignore
```

详见 [.gitattributes 官方示例](https://github.com/laravel/react-starter-kit/blob/main/.gitattributes)。

## 发布到 Packagist

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

<Steps>
  <Step title="在 GitHub 准备公开仓库">
    确保 `composer.json` 的 `name` 与仓库 URL 一致后再公开。
  </Step>

  <Step title="登记到 Packagist">
    在 [Packagist](https://packagist.org/) 注册仓库。发布后 `example/starter-kit` 就可以被解析到。
  </Step>

  <Step title="在 README 中写明使用命令">
    向用户提供如下引入命令。

    ```bash theme={null}
    laravel new my-app --using=example/starter-kit
    ```
  </Step>
</Steps>

## laravel new 命令的流程

`laravel/installer` 的 `NewCommand` 在指定 Starter Kit 时会切换 `create-project` 目标并依次执行初始化命令。

```mermaid theme={null}
flowchart TD
    A["laravel new my-app --using=example/starter-kit"] --> B["用 getStarterKit() 决定包名"]
    B --> C["composer create-project example/starter-kit my-app"]
    C --> D["composer run post-root-package-install -d my-app"]
    D --> E["执行 artisan key:generate 等初始化"]
    E --> F["按需运行 migrate / npm install"]
```

[NewCommand.php](https://github.com/laravel/installer/blob/master/src/NewCommand.php) 中可参考的位置：

* [--using 选项定义](https://github.com/laravel/installer/blob/958a4e7c1386199a63d3c5e49a18b2e5c2ad1600/src/NewCommand.php#L119)
* [`create-project` 与 `post-root-package-install` 的执行](https://github.com/laravel/installer/blob/958a4e7c1386199a63d3c5e49a18b2e5c2ad1600/src/NewCommand.php#L521-L569)
* [`getStarterKit()` 实现](https://github.com/laravel/installer/blob/958a4e7c1386199a63d3c5e49a18b2e5c2ad1600/src/NewCommand.php#L1237-L1255)

## 前端框架的选择

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 为主）  | 想聚焦于特定认证方式          |

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

## 版本升级维护

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

### 应对 Laravel、PHP 版本升级

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

```json theme={null}
"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 发布后能立刻跟进的运营流程。
* **搭配阅读相关指南**：结合[包开发基础](/zh/advanced/package-development)与[包的版本兼容性管理](/zh/advanced/package-versioning)会让设计更稳。


## Related topics

- [Laravel Fortify 与 Starter Kit](/zh/advanced/fortify.md)
- [控制器](/zh/controllers.md)
- [路由](/zh/routing.md)
- [Eloquent 集合](/zh/eloquent-collections.md)
- [教程 - Laravel Console Starter](/zh/packages/laravel-console-starter/tutorial.md)