> ## 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 验证"]
```

## 为什么需要这个骨架

如果“凭感觉”开始写 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` 的提示中,只选择需要的功能。未选择功能对应的脚手架会被自动删除。

| 功能           | 说明                  |
| ------------ | ------------------- |
| Config file  | 在 `config/` 下添加配置文件 |
| Routes       | 添加路由文件              |
| Views        | 添加 Blade 视图         |
| Translations | 添加语言文件              |
| Migrations   | 添加迁移文件              |
| Assets       | 添加对外发布的资源文件         |
| Commands     | 添加 Artisan 命令       |
| Facade       | 添加 Facade 类         |
| Boost Skill  | 添加用于 AI 智能体的技能      |

## 可选的工具

功能之外,也可以按项目需要开关各种工具。

| 工具              | 说明                   |
| --------------- | -------------------- |
| Dependabot      | 依赖的自动更新 PR           |
| Issue Template  | GitHub Issue 模板      |
| Changelog       | 发布时自动更新 CHANGELOG.md |
| Funding         | GitHub Sponsors 赞助链接 |
| Security Policy | 安全漏洞报告策略             |

## 搭建流程

<Steps>
  <Step title="基于模板创建仓库">
    在 GitHub 上点击 **Use this template** 创建新仓库,或者直接克隆。

    ```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`。

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

指定功能标志时,只会包含指定的功能。省略标志时会包含所有功能。

## GitHub Actions CI

骨架里的 `tests.yml` 是一个矩阵构建,会对多种 PHP、Laravel 版本和操作系统组合运行测试。

```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 标签对变更进行分类生成发布说明。

发布说明中的标签:

| 标签               | 分类      |
| ---------------- | ------- |
| `breaking`       | 破坏性变更   |
| `enhancement`    | 新增功能    |
| `bug`            | Bug 修复  |
| `documentation`  | 文档      |
| `dependencies`   | 依赖      |
| `maintenance`    | 维护      |
| `skip-changelog` | 不进入变更日志 |

## configure.php 做的事

`configure.php` 是一个只运行一次的配置 bootstrap 脚本,运行完就会被删除。

```mermaid theme={null}
graph LR
    A["运行 configure.php"] --> B["替换占位符<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** —— 骨架里没有包含自动合并的工作流
* **创建发布说明所需的标签** —— `breaking`、`enhancement`、`bug`、`documentation`、`dependencies`、`maintenance`、`skip-changelog`、`duplicate`
* **设置 `main` 分支保护** —— Changelog 自动化会通过 GitHub Actions 向 `CHANGELOG.md` 提交,分支保护规则需要相应调整

不需要额外的仓库 secrets。骨架里的工作流使用 GitHub 内置的 `GITHUB_TOKEN`。

## 当前开发状态

* **GitHub 仓库**:[laravel/package-skeleton](https://github.com/laravel/package-skeleton)
* **公开时间**:2026 年 7 月(积极开发中)
* **注意**:仍处于开发早期,API 和结构可能会变更

如果你现在要开始写 Laravel 包,与其自己从零搭一个骨架,不如从这个模板起步。它凝聚了 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/advanced/package-versioning.md)
- [Laravel 包开发](/zh/advanced/package-development.md)
- [使用 Testbench Workbench 进行包开发](/zh/advanced/package-workbench.md)
- [如何创建 Laravel Starter Kit](/zh/advanced/starter-kit-creation.md)
- [延迟 Service Provider](/zh/advanced/deferred-provider.md)