---
url: /docs/5.0/plugin/quickstart.md
---
# 插件快速入门

> 🚀 本章帮助你快速了解 CatchAdmin 插件系统，并在 **5 分钟内**创建你的第一个插件。

## 什么是 CatchAdmin 插件？

CatchAdmin 插件是一种基于 **Composer 包管理机制**的扩展系统，允许开发者以模块化的方式为 CatchAdmin 添加功能。

:::tip 💡 好消息
CatchAdmin 并没有发明新的插件规范——只要你会开发 Composer 包，就已经会开发 CatchAdmin 插件了！

如果你还不熟悉 Composer 包开发，通过本教程学习 CatchAdmin 插件开发，也能同时掌握 Composer 包的开发技能，一举两得！
:::

## 第一步：创建插件

使用 CatchAdmin 提供的初始化命令，可以快速创建一个标准的 Composer 包结构。

在项目根目录执行：

```shell
php artisan catch:plugin-init
```

命令会引导你输入以下信息：

| 输入项 | 说明 | 示例 |
|--------|------|------|
| 插件标题 | 插件的显示名称（建议中文） | `测试插件` |
| 包名 | 符合 Composer 规范的包名 | `test/test` |
| 描述 | 插件功能说明 | `这是一个测试插件` |
| 版本号 | 语义化版本号（默认 1.0.0） | `1.0.0` |
| 作者名称 | 系统会自动提取 Git 配置 | `JoJo <xxx@xxx.com>` |
| PSR-4 命名空间 | 插件的根命名空间 | `Test\Test` |

按提示输入完成后，看到以下信息说明初始化成功：

![CatchAdmin 创建一个新插件包](https://image.catchadmin.com/202512151517370.png)

## 插件目录结构

插件会在项目根目录的 `packages` 目录下生成，例如 `packages/test/test`：

![CatchAdmin 插件结构](https://image.catchadmin.com/202512151521606.png)

初始化后的目录结构非常简洁：

```
├─test/
│  ├─src/                  # 源代码目录
│  │  └─ ...               # 你的业务代码
│  ├─hook.php              # 插件生命周期钩子
│  ├─composer.json         # Composer 配置文件
│  └─README.md             # 说明文档
```

> 📌 关于 `hook.php` 的详细用法，请参考 [生命周期钩子](./hook.md)

:::tip 📂 关于目录结构
这只是最基础的结构，后续可以根据需要添加 `routes/`、`migrations/`、`config/` 等目录。详见 [插件开发实战](./practice.md)。
:::

## 第二步：编写代码

在正式安装插件之前，让我们先添加一些代码来验证插件是否正常工作。

### 创建测试类

在 `src` 目录下创建 `Hello.php` 文件：

```php
<?php
declare(strict_types=1);

namespace Test\Test;

class Hello
{
    public function plugin()
    {
        return "hello catchadmin plugin!!! 😀";
    }
}
```

## 第三步：安装插件

### 配置 Composer 仓库

在项目根目录的 `composer.json` 中，添加 `repositories` 配置（如果已存在则跳过）：

```json
{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/*/*"
        },
        {
            "type": "path",
            "url": "./packages/*"
        }
    ]
}
```

### 执行安装命令

```shell
composer require test/test:* --ignore-platform-reqs
```

看到以下输出说明安装成功：

```
./composer.json has been updated
Running composer update test/test
Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking test/test (1.0.0)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 1 install, 0 updates, 0 removals
  - Installing test/test (1.0.0): Junctioning from ./packages/test/test
Generating optimized autoload files
```

## 第四步：验证插件

现在让我们验证插件是否正常工作。

### 使用 Tinker 测试

打开终端，进入 Laravel Tinker：

```shell
php artisan tinker
```

在 Tinker 中执行：

```php
(new Test\Test\Hello)->plugin()
```

输出结果：

![运行插件](https://image.catchadmin.com/202512160747863.png)

🎉 **恭喜！** 看到 `hello catchadmin plugin!!! 😀` 说明你的第一个插件已经成功运行了！

## 卸载插件

卸载插件与标准 Composer 操作完全一致：

```shell
composer remove test/test --ignore-platform-reqs
```

## 打包插件

如果你想将插件发布到 CatchAdmin 插件市场，需要先打包。

### 执行打包命令

```shell
php artisan catch:plugin-pack
```

按提示输入插件名称（如 `test/test`）：

![打包插件](https://image.catchadmin.com/202512160753425.png)

打包完成后，会在 `packages/` 目录生成 `testtest-1.0.0.zip` 文件。

## 下一步

恭喜你完成了第一个插件的创建！🎊

接下来，你可以继续学习 [插件开发实战](./practice.md)，了解如何开发一个完整的后台模块插件，包括：

* 数据库迁移
* 模型与控制器
* 路由配置
* Vue 前端页面
* [生命周期钩子](./hook.md)

:::info 💬 加入社区
如果你有兴趣为 CatchAdmin 插件生态做贡献，欢迎添加微信 `catchadmin`，我们将手把手指导你解决开发中遇到的问题。

添加好友时请备注 `插件`
:::