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

手把手教你创建、测试、版本管理、发布和维护自己的 Laravel 扩展包。

引言 ​

Laravel 生态之所以繁荣，离不开开源社区的贡献。你每天用的 Spatie、Laravel Debugbar、Livewire，本质上都是开发者分享出来的扩展包。

如果你写过一些能在多个项目里复用的功能——自定义验证规则、辅助函数、UI 组件之类的——那恭喜，你其实已经有了做扩展包的基础。

这篇文章会带你走完整个流程：从搭建项目结构，到编写测试、配置 CI/CD，最后发布到 Packagist。

还不是会员？点击这里阅读完整文章！

步骤 1：搭建扩展包结构 ​

先从最基础的开始。

我们要做一个叫 mycompany/laravel-awesome 的扩展包，功能很简单：提供一个 @shout() 的 Blade 指令。

1. 创建扩展包文件夹 ​

在 Laravel 项目里（或者单独建个目录），执行：

bash
mkdir -p packages/mycompany/laravel-awesome
cd packages/mycompany/laravel-awesome

2. 初始化 Composer ​

bash
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
<?php

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

2. 添加服务提供者 ​

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

src/LaravelAwesomeServiceProvider.php：

php
<?php

namespace 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 去哪找这个类：

json
"autoload": {
    "psr-4": {
        "MyCompany\\LaravelAwesome\\": "src/"
    }
},
"extra": {
    "laravel": {
        "providers": [
            "MyCompany\\LaravelAwesome\\LaravelAwesomeServiceProvider"
        ]
    }
}

最后刷新一下自动加载：

bash
composer dump-autoload

在 Laravel 项目里试试：

blade
@shout('hello world')

输出 → HELLO WORLD

完成！你的第一个 Laravel 扩展包就这么跑起来了。

步骤 3：加上测试 ​

这里用 Pest，语法比 PHPUnit 简洁不少。

先装 Pest：

bash
composer require pestphp/pest --dev

创建 tests/ExampleTest.php：

php
<?php

it('将文本转换为大写', function () {
    $result = strtoupper('laravel');
    expect($result)->toBe('LARAVEL');
});

运行测试：

bash
vendor/bin/pest

把测试放在扩展包目录里，这样即使 Laravel 升级了，你也能及时发现兼容性问题。

步骤 4：本地测试 ​

发布之前，先在另一个 Laravel 项目里测一下。

在主项目的 composer.json 里加上：

json
"repositories": [
    {
        "type": "path",
        "url": "packages/mycompany/laravel-awesome"
    }
],

然后安装：

bash
composer require mycompany/laravel-awesome:*

这样就能快速迭代，不用每次都推到 GitHub。

步骤 5：配置 CI/CD ​

用 GitHub Actions 自动跑测试。新建 .github/workflows/tests.yml：

yaml
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）规范。

发布时这么操作：

bash
git add .
git commit -m "Initial release"
git tag v1.0.0
git push origin main --tags

打上 tag 后，CI 会自动跑，Composer 也能根据 tag 管理版本。

步骤 7：发布到 Packagist ​

  1. 把代码推到 GitHub（公开仓库）
  2. 打开 https://packagist.org
  3. 点 Submit，贴上仓库地址
  4. Packagist 会自动从 tag 里拉取版本

现在别人就能装你的扩展包了：

bash
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：

yaml
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 生态做出贡献。

一旦掌握了这套流程，你会发现自己写的代码越来越模块化、越来越好复用，而且能帮助到更多开发者。

题外话：最近花了很久的时间零零散散的将 Laravel Livewire4 的文档翻译成了中文，如果对 Laravel Livewire 感兴趣，可以查看文档 Laravel Livewire4 中文文档

CatchAdmin
后端开发工程师，前端入门选手，略知相关服务器知识，偏爱❤️ Laravel & Vue
CatchAdmin 一款基于 Laravel + Vu3 现代化 PHP 后台管理框架
本作品采用《CC 协议》，转载必须注明作者和本文链接