当前位置：首页 > news >正文

从零开始打造 Laravel 扩展包：开发、测试到发布完整指南

news 2025/11/9 10:49:07

从零开始打造 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

<?phpif (! function_exists('shout')) {/*** 将给定字符串转换为大写。** @param  string  $text* @return string*/function shout(string $text): string{return strtoupper($text);}
}

2. 添加服务提供者

再创建一个服务提供者文件：

src/LaravelAwesomeServiceProvider.php：

<?phpnamespace MyCompany\LaravelAwesome;use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Blade;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：

<?phpit('将文本转换为大写', 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: Testson: [push, pull_request]jobs:test:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: shivammathur/setup-php@v2with: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（公开仓库）
打开 https://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 Releaseon:push:tags:- 'v*.*.*'jobs:release:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- uses: ncipollo/release-action@v1with:generateReleaseNotes: true