FastAdmin 插件开发实战：从零开发自定义插件

前言

FastAdmin 的插件系统是其生态的核心——通过在线安装插件，可以快速扩展论坛、CMS、商城等功能模块，无需修改框架核心代码。本文将从零开始，带你完整开发一个 FastAdmin 插件。

一、插件目录结构

一个标准的 FastAdmin 插件目录如下：

addons/
└── mydemo/                        # 插件目录（插件标识）
    ├── Mydemo.php                 # 插件主类
    ├── config.php                 # 插件配置文件
    ├── info.ini                   # 插件信息文件
    ├── controller/
    │   └── Index.php              # 插件控制器
    ├── model/
    │   └── Demo.php               # 插件模型
    ├── view/
    │   └── index/
    │       └── index.html         # 插件视图
    ├── public/
    │   ├── css/
    │   │   └── mydemo.css         # 插件样式
    │   └── js/
    │       └── mydemo.js          # 插件脚本
    └── hooks.php                  # 钩子定义（可选）

二、创建插件

2.1 使用命令行创建

php think addon -a mydemo -c create

这会在 addons/mydemo/ 目录下自动生成插件骨架文件。

2.2 info.ini 插件信息

name = mydemo
title = 示例插件
description = 这是一个 FastAdmin 示例插件
author = Your Name
version = 1.0.0
state = 1

字段	说明
`name`	插件标识（目录名，全小写）
`title`	插件名称
`description`	插件描述
`author`	作者
`version`	版本号
`state`	状态：1=正常，0=禁用

2.3 插件主类 Mydemo.php

<?php
namespace addons\mydemo;

use think\Addons;

class Mydemo extends Addons
{
    // 插件安装时执行
    public function install()
    {
        // 创建数据表
        $sql = "CREATE TABLE IF NOT EXISTS `fa_mydemo` (
            `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
            `title` varchar(100) NOT NULL DEFAULT '',
            `content` text,
            `createtime` int(10) unsigned NOT NULL DEFAULT '0',
            PRIMARY KEY (`id`)
        ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;";
        \think\Db::execute($sql);
        return true;
    }

    // 插件卸载时执行
    public function uninstall()
    {
        // 删除数据表
        \think\Db::execute("DROP TABLE IF EXISTS `fa_mydemo`");
        return true;
    }

    // 插件启用时执行
    public function enable()
    {
        return true;
    }

    // 插件禁用时执行
    public function disable()
    {
        return true;
    }

    // 钩子：在后台首页显示
    public function adminIndexTop($params)
    {
        echo '<div class="alert alert-info">欢迎使用 Mydemo 插件！</div>';
    }
}

2.4 config.php 插件配置

<?php
return [
    [
        'name'    => 'title',
        'title'   => '插件标题',
        'type'    => 'text',
        'content' => '',
        'value'   => 'Mydemo Plugin',
        'rule'    => 'required',
        'msg'     => '请填写插件标题',
        'tip'     => '显示在插件管理页面的标题',
    ],
    [
        'name'    => 'display_count',
        'title'   => '显示数量',
        'type'    => 'number',
        'content' => '',
        'value'   => '10',
        'rule'    => 'required',
        'msg'     => '请填写显示数量',
        'tip'     => '前台显示的数据条数',
    ],
    [
        'name'    => 'is_open',
        'title'   => '是否开启',
        'type'    => 'radio',
        'content' => ['0' => '关闭', '1' => '开启'],
        'value'   => '1',
        'rule'    => 'required',
        'msg'     => '',
        'tip'     => '',
    ],
];

配置在后台 → 插件管理 → 配置中可编辑，读取方式：

$config = get_addon_config('mydemo');
$title = $config['title'];

三、插件控制器

3.1 后台控制器

<?php
// addons/mydemo/controller/Index.php
namespace addons\mydemo\controller;

use app\common\controller\Backend;
use think\Db;

class Index extends Backend
{
    // 不需要登录的方法
    protected $noNeedLogin = [];
    
    // 不需要权限验证的方法
    protected $noNeedRight = [];

    /**
     * 插件后台首页
     */
    public function index()
    {
        $list = Db::name('mydemo')->order('id', 'desc')->paginate(15);
        $this->view->assign('list', $list);
        return $this->view->fetch();
    }

    /**
     * 添加数据
     */
    public function add()
    {
        if ($this->request->isPost()) {
            $data = $this->request->post('row/a');
            $data['createtime'] = time();
            Db::name('mydemo')->insert($data);
            $this->success('添加成功');
        }
        return $this->view->fetch();
    }

    /**
     * 删除数据
     */
    public function del($ids = null)
    {
        Db::name('mydemo')->where('id', 'in', $ids)->delete();
        $this->success('删除成功');
    }
}

3.2 访问路由

插件控制器的 URL 格式为：

http://yourdomain.com/addons/mydemo/index/index

对应：

addons - 固定前缀
mydemo - 插件标识
index - 控制器名
index - 方法名

3.3 前台控制器

<?php
// addons/mydemo/controller/Api.php
namespace addons\mydemo\controller;

use app\common\controller\Api;

class Api extends Api
{
    // 不需要登录的方法
    protected $noNeedLogin = ['getList'];

    /**
     * 获取数据列表（API 接口）
     */
    public function getList()
    {
        $count = \think\Db::name('mydemo')->count();
        $list = \think\Db::name('mydemo')
            ->order('id', 'desc')
            ->limit(10)
            ->select();

        $this->success('获取成功', [
            'total' => $count,
            'list'  => $list,
        ]);
    }
}

四、钩子机制（Hook）

4.1 注册钩子

在插件主类中定义钩子方法，方法名即钩子名：

// addons/mydemo/Mydemo.php
class Mydemo extends Addons
{
    // 钩子：文章详情页底部
    public function articleDetailBottom($params)
    {
        // $params 是传递的参数
        $article = $params['article'];
        
        // 输出自定义内容
        echo '<div class="mydemo-box">';
        echo '<h3>相关推荐</h3>';
        echo '</div>';
    }

    // 钩子：后台导航栏
    public function adminSidebar($params)
    {
        echo '<li><a href="' . addon_url('mydemo/index/index') . '">';
        echo '<i class="fa fa-puzzle-piece"></i> <span>Mydemo</span>';
        echo '</a></li>';
    }
}

4.2 触发钩子

在任意位置触发钩子：

// 传递参数给钩子
\think\Hook::listen('article_detail_bottom', ['article' => $article]);

4.3 FastAdmin 内置常用钩子

钩子名	触发位置	参数
`admin_index_top`	后台首页顶部	无
`admin_sidebar`	后台左侧菜单	无
`article_detail_bottom`	文章详情底部	article 数据
`user_register_after`	用户注册后	user 数据
`config_init`	配置初始化	配置数组

五、插件打包发布

5.1 打包

# 将插件目录打包为 zip
cd addons
zip -r mydemo.zip mydemo/

注意：打包时不要包含 runtime、temp 等临时目录。

5.2 发布到插件市场

注册 FastAdmin 官网账号
进入"开发者中心"
点击"发布插件"
上传 zip 包，填写插件信息
等待审核通过

5.3 版本更新

更新 info.ini 中的版本号后重新打包上传，用户可在后台一键升级。

六、调试技巧

6.1 开启插件调试

// application/config.php
'app_debug' => true;

// 确保插件目录有读写权限
chmod -R 755 addons/mydemo/

6.2 查看插件日志

// 在插件代码中记录日志
\think\Log::info('Mydemo: ' . json_encode($data));

// 查看日志
// runtime/log/202607/24.log

6.3 热更新

开发阶段修改插件代码后，清除缓存即可生效：

php think clear --type=cache
php think clear --type=temp

七、完整插件开发流程

1. php think addon -a mydemo -c create     → 创建骨架
2. 编辑 info.ini                            → 填写插件信息
3. 编辑 Mydemo.php                          → 实现安装/卸载/钩子
4. 编辑 config.php                          → 定义插件配置项
5. 编写 controller/                         → 实现业务逻辑
6. 编写 view/                               → 编写视图模板
7. 编写 public/                             → 添加前端资源
8. 后台安装插件 → 测试 → 调试
9. 打包 zip → 发布

总结

FastAdmin 插件系统通过目录约定 + 钩子机制实现了松耦合的功能扩展。核心要点：

插件主类继承 think\Addons，实现 install/uninstall 生命周期
通过 config.php 定义可视化配置项
通过 Hook::listen() 在框架任意位置触发钩子
插件可以有自己的 MVC 结构，独立于主应用