从零开始打造 Laravel 扩展包：开发、测试到发布完整指南
手把手教你创建、测试、版本管理、发布和维护自己的 Laravel 扩展包。
引言
Laravel 生态之所以繁荣，离不开开源社区的贡献。你每天用的 Spatie、Laravel Debugbar、Livewire，本质上都是开发者分享出来的扩展包。
如果你写过一些能在多个项目里复用的功能——自定义验证规则、辅助函数、UI 组件之类的——那恭喜，你其实已经有了做扩展包的基础。
这篇文章会带你走完整个流程：从搭建项目结构，到编写测试、配置 CI/CD，最后发布到 Packagist。
原文链接 从零开始打造 Laravel 扩展包：开发、测试到发布完整指南
步骤 1：搭建扩展包结构
先从最基础的开始。
我们要做一个叫 mycompany/laravel-awesome 的扩展包，功能很简单：提供一个 @shout() 的 Blade 指令。
1. 创建扩展包文件夹
在 Laravel 项目里（或者单独建个目录），执行：
mkdir -p packages/mycompany/laravel-awesome
cd packages/mycompany/laravel-awesome
2. 初始化 Composer
composer init
3. 文件夹结构
最简单的扩展包结构长这样：
laravel-awesome/
├── composer.json.json
├── src/
│ ├── LaravelAwesomeServiceProvider.php
│ └── Helpers/
│ └── shout.php
└── tests/
└── ExampleTest.php
步骤 2：编写辅助函数和服务提供者
1. 添加辅助函数：Helpers/shout.php
在扩展包里新建文件：
src/Helpers/shout.php
<?php
if (! function_exists(\'shout\')) {
/**
* 将给定字符串转换为大写。
*
* @param string $text
* @return string
*/
function shout(string $text): string
{
return strtoupper($text);
}
}
2. 添加服务提供者
再创建一个服务提供者文件：
src/LaravelAwesomeServiceProvider.php：
<?php
namespace MyCompanyLaravelAwesome;
use IlluminateSupportServiceProvider;
use IlluminateSupportFacadesBlade;
class LaravelAwesomeServiceProvider extends ServiceProvider
{
public function boot()
{
// 注册 Blade 指令
Blade::directive(\'shout\', function ($expression) {
return \"<?php echo strtoupper($expression); ?>\";
});
// 加载辅助函数文件
$this->loadHelpers();
}
public function register()
{
//
}
protected function loadHelpers(): void
{
foreach (glob(__DIR__ . \'/Helpers/*.php\') as $filename) {
require_once $filename;
}
}
}
3. 配置自动加载
在 composer.json 里告诉 Laravel 去哪找这个类：
\"autoload\": {
\"psr-4\": {
\"MyCompany\\LaravelAwesome\\\": \"src/\"
}
},
\"extra\": {
\"laravel\": {
\"providers\": [
\"MyCompany\\LaravelAwesome\\LaravelAwesomeServiceProvider\"
]
}
}
最后刷新一下自动加载：
composer dump-autoload
在 Laravel 项目里试试：
@shout(\'hello world\')
输出 → HELLO WORLD
完成！你的第一个 Laravel 扩展包就这么跑起来了。
步骤 3：加上测试
这里用 Pest，语法比 PHPUnit 简洁不少。
先装 Pest：
composer require pestphp/pest --dev
创建 tests/ExampleTest.php：
<?php
it(\'将文本转换为大写\', function () {
$result = strtoupper(\'laravel\');
expect($result)->toBe(\'LARAVEL\');
});
运行测试：
vendor/bin/pest
把测试放在扩展包目录里，这样即使 Laravel 升级了，你也能及时发现兼容性问题。
步骤 4：本地测试
发布之前，先在另一个 Laravel 项目里测一下。
在主项目的 composer.json 里加上：
\"repositories\": [
{
\"type\": \"path\",
\"url\": \"packages/mycompany/laravel-awesome\"
}
],
然后安装：
composer require mycompany/laravel-awesome:*
这样就能快速迭代，不用每次都推到 GitHub。
步骤 5：配置 CI/CD
用 GitHub Actions 自动跑测试。新建 .github/workflows/tests.yml：
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
with:
php-version: \'8.3\'
- run: composer install --prefer-dist --no-progress
- run: vendor/bin/pest
这样每次 push 代码，测试就会自动跑一遍。
步骤 6：版本管理
扩展包的版本管理很重要，要遵循语义化版本（SemVer）规范。
发布时这么操作：
git add .
git commit -m \"Initial release\"
git tag v1.0.0
git push origin main --tags
打上 tag 后，CI 会自动跑，Composer 也能根据 tag 管理版本。
步骤 7：发布到 Packagist
- 把代码推到 GitHub（公开仓库）
- 打开 packagist.org
- 点 Submit，贴上仓库地址
- Packagist 会自动从 tag 里拉取版本
现在别人就能装你的扩展包了：
composer require mycompany/laravel-awesome
步骤 8：后期维护
扩展包发布后，还要持续维护：
- 支持多个 Laravel 版本（8.x 到 12.x），自动跑测试
- 用 Dependabot 或 Renovate 自动更新依赖
- README.md 里写清楚使用示例
- 给仓库加上 topic：laravel、package、blade 等
- 发新版本时遵循语义化版本：
- MAJOR（大版本）：不兼容的变更
- MINOR（小版本）：新功能
- PATCH（补丁）：修 bug
进阶技巧：Monorepo 管理多个扩展包
如果你有多个扩展包（比如一套 UI 组件），可以用 monorepo 的方式统一管理，配合 laravel/pint 和 phpstan 这些工具共享配置。
这样做的好处是代码风格统一，依赖更新也方便。
额外福利：自动发布
再加个工作流 .github/workflows/release.yml：
name: Auto Release
on:
push:
tags:
- \'v*.*.*\'
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ncipollo/release-action@v1
with:
generateReleaseNotes: true
这样每次打 tag，GitHub 就会自动生成 release 页面，Packagist 也会同步。
总结
到这里，你已经走完了从想法到发布的全流程：搭建结构 → 编写代码 → 测试 → CI/CD → Packagist 发布。
做扩展包不只是分享代码那么简单，它让你深入了解开源项目的运作机制，学会如何维护一个公开的项目，也能为 Laravel 生态做出贡献。
一旦掌握了这套流程，你会发现自己写的代码越来越模块化、越来越好复用，而且能帮助到更多开发者。
