> ## 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 Package Skeleton — 官方套件用起始模板

> 初步調查 laravel/package-skeleton。彙整 Laravel 套件開發最佳實踐的官方起始模板。內建 Pest、Larastan、Pint、Workbench、GitHub Actions CI 的完整組合。

<Info>
  本文根據原始碼調查整理。截至 2026 年 7 月，仍為開發中的儲存庫。
</Info>

## 什麼是 Laravel Package Skeleton

[Laravel Package Skeleton](https://github.com/laravel/package-skeleton) 是製作 Laravel 套件時使用的起始模板。

```bash theme={null}
git clone https://github.com/laravel/package-skeleton.git my-package
cd my-package
composer install
```

執行 `composer install` 後會自動啟動互動式設定腳本（`configure.php`），以一問一答方式設定套件名稱、vendor 名稱、命名空間、要使用的功能。設定完成後就能立刻開始開發。

```mermaid theme={null}
graph TD
    A["GitHub 的<br>Use this template"] --> B["composer install"]
    B --> C["自動執行 configure.php"]
    C --> D{"互動式設定"}
    D --> E["套件名稱、vendor、命名空間"]
    D --> F["選擇要使用的功能"]
    E --> G["設定完成"]
    F --> G
    G --> H["以 composer test 檢驗"]
```

## 為何需要這個 skeleton

「自我流」開始寫 Laravel 套件時，會在測試環境設定、靜態分析、程式碼格式化、GitHub Actions 等與套件本身邏輯無關的事情上花很多時間。

Laravel Package Skeleton 把 Laravel 團隊實際開發套件所用的最佳實踐集中到一份模板。使用它就能跳過「建立環境」直接開始實作套件邏輯。

## 內建的工具

| 工具                                                       | 角色            |
| -------------------------------------------------------- | ------------- |
| [Pest](https://pestphp.com/)                             | 測試框架          |
| [Larastan](https://github.com/larastan/larastan)         | Laravel 用靜態分析 |
| [Pint](https://laravel.com/docs/pint)                    | 程式碼格式化工具      |
| [Orchestra Testbench](https://packages.tools/testbench/) | 套件測試環境        |
| Workbench                                                | 端對端開發用應用      |

## 可設定的套件功能

`composer install` 的 prompt 中可選擇需要的功能。未選功能的 scaffold 會被刪除。

| 功能           | 說明                  |
| ------------ | ------------------- |
| Config file  | 於 `config/` 加入設定檔   |
| Routes       | 加入路由檔               |
| Views        | 加入 Blade view       |
| Translations | 加入語系檔               |
| Migrations   | 加入 migration 檔      |
| Assets       | 加入公開資源              |
| Commands     | 加入 Artisan 指令       |
| Facade       | 加入 Facade 類別        |
| Boost Skill  | 加入 AI Agent 用 skill |

## 可設定的工具

與功能相同，可依專案需求開關工具。

| 工具              | 說明                   |
| --------------- | -------------------- |
| Dependabot      | 相依自動更新 PR            |
| Issue Template  | GitHub Issue 模板      |
| Changelog       | 發佈時自動更新 CHANGELOG.md |
| Funding         | GitHub Sponsors 贊助連結 |
| Security Policy | 資安漏洞回報政策             |

## 建置流程

<Steps>
  <Step title="由模板建立儲存庫">
    按 GitHub 上的 **Use this template** 按鈕建立新儲存庫，或直接 clone。

    ```bash theme={null}
    git clone https://github.com/laravel/package-skeleton.git my-package
    cd my-package
    ```
  </Step>

  <Step title="安裝相依">
    執行 `composer install` 時會自動啟動 `configure.php`。

    ```bash theme={null}
    composer install
    ```

    若要手動執行腳本，可用 `--no-scripts` 選項。

    ```bash theme={null}
    composer install --no-scripts
    php configure.php
    ```
  </Step>

  <Step title="回答提問">
    以一問一答方式設定：

    * Author Name / Email
    * Vendor 名（例：`kawax`）
    * Package 名（例：`my-package`）
    * Package 描述
    * Class 名（例：`MyPackage`）
    * 選擇使用功能（多選）
    * 選擇使用工具（多選）
    * 是否自動建立 GitHub 儲存庫（若已驗證 gh CLI）
  </Step>

  <Step title="測試運作">
    ```bash theme={null}
    composer test
    ```

    會依 PHPStan → Pint → 型別覆蓋 → Pest 順序執行所有檢查。
  </Step>

  <Step title="用 Workbench 進行端對端測試">
    ```bash theme={null}
    composer serve
    ```

    會在 `http://localhost:8000` 啟動一個檢驗套件的簡易 Laravel 應用。
  </Step>
</Steps>

## 非互動模式

若要從 CI 或腳本安裝，使用 `--no-interaction` flag。

```bash theme={null}
php configure.php --no-interaction --config --routes
```

指定功能 flag 就只會包含指定的功能。若省略則包含全部功能。

## GitHub Actions CI

skeleton 內含的 `tests.yml` 是以多個 PHP 版本、Laravel 版本、OS 組合執行測試的 matrix build。

```yaml theme={null}
matrix:
  os: [ubuntu-latest, windows-latest]
  php: [8.3, 8.4, 8.5]
  laravel: [12.*, 13.*]
  stability: [prefer-lowest, prefer-stable]
```

每個 job 的執行內容：

1. **PHPStan**（`composer analyse`）— 靜態分析
2. **Pint**（`composer lint:check`）— 樣式檢查
3. **型別覆蓋**（`composer test:types`）— 確認型別覆蓋 100%（僅 Ubuntu）
4. **Pest**（`composer test:unit`）— 單元測試（僅 Ubuntu）

## Changelog 自動化

`update-changelog.yml` 以 GitHub Release 為觸發自動更新 `CHANGELOG.md`。`release.yml` 依 PR label 分類變更並產生 release note。

release note 的 label：

| Label            | 分類      |
| ---------------- | ------- |
| `breaking`       | 破壞性變更   |
| `enhancement`    | 功能新增    |
| `bug`            | Bug 修正  |
| `documentation`  | 文件      |
| `dependencies`   | 相依      |
| `maintenance`    | 維護      |
| `skip-changelog` | 不列入變更紀錄 |

## configure.php 的行為

`configure.php` 是設定腳本，僅執行 1 次的 bootstrap。執行後會自我刪除。

```mermaid theme={null}
graph LR
    A["執行 configure.php"] --> B["替換 placeholder<br>:vendor_slug/:package_slug<br>:author_name 等"]
    B --> C["刪除未使用的功能檔案"]
    C --> D["README_PACKAGE.md → README.md<br>AGENTS_PACKAGE.md → AGENTS.md"]
    D --> E["將 CLAUDE.md 連結到 AGENTS.md<br>將 .claude 連結到 .agents"]
    E --> F["刪除腳本本身"]
```

## 安裝後的 GitHub 設定

README 建議安裝後的設定：

* **Dependabot PR 手動 review** — 不含自動合併工作流程
* **建立 release note label** — `breaking`、`enhancement`、`bug`、`documentation`、`dependencies`、`maintenance`、`skip-changelog`、`duplicate`
* **設定 `main` 分支保護** — Changelog 自動化會由 GitHub Actions commit `CHANGELOG.md`，需調整分支保護規則

不需要額外的 repo secret。內建 workflow 使用 GitHub 的內建 `GITHUB_TOKEN`。

## 目前開發狀況

* **GitHub 儲存庫**：[laravel/package-skeleton](https://github.com/laravel/package-skeleton)
* **公開時期**：2026 年 7 月（積極開發中）
* **注意**：目前仍為早期階段，API 或結構有可能變更

要開始寫 Laravel 套件的人，建議從此模板開始，勝過自己從零建構 skeleton。裡面凝結了 Laravel 團隊多年的套件開發最佳實踐。

<Card title="laravel/package-skeleton 儲存庫" icon="github" href="https://github.com/laravel/package-skeleton">
  原始碼與最新資訊請見此處。
</Card>

<Card title="套件開發官方文件" icon="book-open" href="https://laravel.com/docs/packages">
  Laravel 套件開發基礎請參考官方文件。
</Card>


## Related topics

- [密碼重設](/zh-TW/passwords.md)
- [起始套件（Starter Kit）](/zh-TW/starter-kits.md)
- [套件的版本相容性管理](/zh-TW/advanced/package-versioning.md)
- [Laravel Head — document <head> 管理套件](/zh-TW/blog/laravel-head-introduction.md)
- [Laravel Agent Detector — AI Agent 偵測套件](/zh-TW/blog/agent-detector-introduction.md)