📦 插件安装

ThinkAdmin 提供完善的插件安装和升级机制，支持多种插件类型和安装方式。通过 Composer 包管理器，可以轻松安装、更新和卸载插件。

📚 基础概念

什么是插件？

插件是扩展 ThinkAdmin 功能的独立模块，可以添加新的功能、修改现有功能或集成第三方服务。

简单理解：就像手机的 App，可以安装各种应用来扩展功能。

插件的作用：

• 功能扩展：添加新功能模块（如支付、商城、微信等）
• 代码复用：将通用功能封装成插件，多个项目共享
• 模块化开发：将大型项目拆分成多个插件，便于管理
• 快速开发：使用现成插件，快速构建功能

插件安装方式

ThinkAdmin 使用 Composer 来管理插件，这是 PHP 的标准依赖管理工具。

Composer 是什么？

• PHP 的包管理器（类似 Node.js 的 npm）
• 用于管理项目依赖和插件
• 自动处理依赖关系和版本冲突
• 支持从 Packagist 或私有仓库安装

安装流程：

# 1. 在项目根目录执行安装命令
composer require zoujingli/think-plugs-admin

# 2. Composer 自动下载插件到 vendor 目录
# 3. 安装器自动执行配置和文件复制
# 4. 插件自动注册到系统

📋 插件类型

ThinkAdmin 支持两种插件类型，根据安装位置和用途不同：

🚀 主要功能

• 多种插件类型: 支持普通应用插件和高级应用插件
• 自动安装: 基于 ThinkInstall 的自动安装机制
• 依赖管理: 自动处理插件依赖关系
• 配置初始化: 自动初始化插件配置文件
• 灵活安装: 支持自定义安装位置
• 安全卸载: 提供安全的插件卸载机制

⚠️ 重要提示

授权协议: 在安装插件前，请仔细阅读应用插件的授权协议，确保您符合使用条件。

文档遵循: 请遵循各插件的说明文档，按照相关指令进行操作。

📋 插件类型

ThinkAdmin 支持两种插件类型，根据安装位置和用途不同：

普通应用插件

普通插件安装在 vendor/package 目录下，不占用 app 目录，插件代码与应用代码完全分离。

什么是普通插件？

• 插件代码保留在 vendor 目录（Composer 标准位置）
• 通过 PSR-4 自动加载机制加载类文件
• 不修改 app 目录，保持应用目录整洁
• 适合功能扩展类插件（如支付插件、微信插件等）

为什么选择普通插件？

• ✅ 代码隔离：插件代码与应用代码完全分离
• ✅ 易于维护：更新插件不影响应用代码
• ✅ 快速卸载：只需执行 composer remove 即可
• ✅ 标准规范：符合 Composer 标准，便于管理

安装位置示例：

项目根目录/
  ├── app/                    # 应用代码（不受影响）
  ├── vendor/                 # Composer 包目录
  │   └── zoujingli/
  │       └── think-plugs-account/  # 插件代码在这里
  │           ├── src/              # 插件源代码
  │           │   ├── Service.php   # 插件服务类
  │           │   └── ...           # 其他类文件
  │           ├── stc/              # 静态资源
  │           │   ├── database/     # 数据库迁移文件
  │           │   └── public/       # 静态资源文件
  │           └── composer.json      # 插件配置文件
  └── composer.json           # 项目配置文件

composer.json 配置详解：

{
  "type": "think-admin-plugin",  // 插件类型标识
  "name": "zoujingli/think-plugs-account",  // 插件包名
  "autoload": {
    "psr-4": {
      // 命名空间映射：plugin\account\ 对应 src 目录
      "plugin\\account\\": "src"
    }
  },
  "extra": {
    "plugin": {
      "copy": {
        // 复制数据库迁移文件到项目目录
        "stc/database": "database/migrations"
      }
    }
  }
}

配置说明：

• type: "think-admin-plugin"：标识这是 ThinkAdmin 插件
• autoload：定义类的自动加载规则
• extra.plugin.copy：定义安装时需要复制的文件

实际应用场景：

• 支付插件（think-plugs-payment）
• 微信插件（think-plugs-wechat）
• 账号管理插件（think-plugs-account）
• 其他功能扩展插件

高级应用插件（模块插件）

模块插件可以安装到 app 目录下的应用目录，安装后代码会复制到应用目录，安装器会自动清理原安装目录。

什么是模块插件？

• 插件代码复制到 app 目录（成为应用的一部分）
• 安装后可以像应用代码一样自由修改
• 适合需要深度定制的核心模块（如后台管理模块）

为什么选择模块插件？

• ✅ 可定制性强：代码在 app 目录，可以随意修改
• ✅ 完全控制：拥有代码的完全控制权
• ✅ 深度集成：与项目代码深度集成
• ⚠️ 注意：卸载时需要手动删除代码

安装位置示例：

项目根目录/
  ├── app/
  │   └── admin/              # 插件代码复制到这里（成为应用的一部分）
  │       ├── controller/     # 控制器目录
  │       ├── model/          # 模型目录
  │       ├── view/           # 视图目录
  │       ├── Service.php     # 服务类
  │       └── ...             # 其他文件
  ├── vendor/                 # 原插件目录会被清理（clear: true）
  └── composer.json

composer.json 配置详解：

{
  "type": "think-admin-plugin",
  "name": "zoujingli/think-plugs-admin",
  "autoload": {
    "psr-4": {
      // 注意：命名空间指向 app\admin（不是 plugin\admin）
      "app\\admin\\": "src"
    }
  },
  "extra": {
    "plugin": {
      "copy": {
        // ! 表示绝对复制：先删除 app/admin，再复制 src 内容
        "src": "!app/admin",
        // 复制数据库迁移文件
        "stc/database": "database/migrations"
      },
      // 安装后清理 vendor 中的插件目录
      "clear": true
    }
  }
}

配置说明：

• "src": "!app/admin"：! 前缀表示绝对复制（先删除目标目录再复制）
• clear: true：安装后清理 vendor 中的插件目录
• 命名空间指向 app\admin，与普通插件不同

实际应用场景：

• 后台管理模块（think-plugs-admin）
• 需要深度定制的核心功能模块
• 需要频繁修改的业务模块

⚙️ 安装机制

📦 普通插件安装

普通插件通过 Composer 安装到 vendor 目录，安装器会自动处理配置文件和资源文件的初始化。

完整安装步骤：

步骤1：执行安装命令

在项目根目录执行 Composer 安装命令：

# 进入项目根目录
cd /path/to/your/project

# 安装插件
composer require zoujingli/think-plugs-account

执行过程：

Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking zoujingli/think-plugs-account (v1.0.0)
Writing lock file
Installing dependencies from lock file
  - Installing zoujingli/think-plugs-account (v1.0.0)
    Downloading (100%)
    Extracting archive

步骤2：安装器自动处理

Composer 安装完成后，ThinkAdmin 的安装器会自动执行以下操作：

1. 初始化插件配置文件

   • 读取插件的 composer.json 配置
   • 解析 extra.plugin 配置项
   • 准备文件复制操作

2. 复制数据库迁移文件

   # 自动执行
   stc/database/* → database/migrations/

3. 复制静态资源文件（如果有配置）

   # 自动执行
   stc/public/* → public/static/

4. 注册插件服务类

   • 自动发现插件的 Service.php 文件
   • 注册到 ThinkAdmin 的服务容器
   • 调用 register() 方法初始化插件

步骤3：插件服务类自动注册

插件通过 Service.php 自动注册，无需手动配置：

<?php
// plugin/account/src/Service.php
namespace plugin\account;

use think\admin\Plugin;

/**
 * 账号管理插件服务类
 * @class Service
 * @package plugin\account
 */
class Service extends Plugin
{
    /**
     * 插件注册方法
     * 系统启动时自动调用
     */
    public function register(): void
    {
        // 注册插件菜单
        $this->menus([
            [
                'name' => '账号管理',
                'icon' => 'layui-icon-user',
                'node' => 'plugin-account/index/index',
            ]
        ]);
        
        // 注册路由
        $this->app->route->get('account/test', 'plugin-account/test/index');
        
        // 注册事件监听
        $this->app->event->listen('UserLogin', function($user) {
            // 用户登录事件处理
        });
    }
}

步骤4：验证安装

安装完成后，可以通过以下方式验证：

# 1. 检查插件目录
ls -la vendor/zoujingli/think-plugs-account/

# 2. 检查数据库迁移文件
ls -la database/migrations/

# 3. 检查插件是否注册（在代码中）
# 访问后台，查看是否有插件菜单

步骤5：卸载插件

如果需要卸载插件：

# 卸载插件（注意：不会删除数据库表和配置文件）
composer remove zoujingli/think-plugs-account

卸载后的清理工作：

1. 删除数据库表（如果需要）

   -- 通过数据库管理工具删除插件相关的表
   DROP TABLE IF EXISTS `plugin_account_user`;
   DROP TABLE IF EXISTS `plugin_account_auth`;

2. 删除配置文件（如果有）

   # 检查是否有插件相关的配置文件
   # 通常在 config/ 目录下

3. 删除静态资源（如果有）

   # 检查 public/static/ 目录下是否有插件资源
   # 根据实际情况决定是否删除

🔧 模块插件安装

模块插件安装后，代码会复制到 app 目录，安装器会自动清理原安装目录。这种安装方式适合需要深度定制的核心模块。

完整安装步骤：

步骤1：执行安装命令

在项目根目录执行安装命令：

# 进入项目根目录
cd /path/to/your/project

# 安装模块插件
composer require zoujingli/think-plugs-admin

执行过程：

Loading composer repositories with package information
Updating dependencies
Lock file operations: 1 install, 0 updates, 0 removals
  - Locking zoujingli/think-plugs-admin (v6.1.0)
Writing lock file
Installing dependencies from lock file
  - Installing zoujingli/think-plugs-admin (v6.1.0)
    Downloading (100%)
    Extracting archive

步骤2：安装器自动处理

安装器会按照 composer.json 中的 extra.plugin 配置执行以下操作：

1. 绝对复制插件代码

   # 执行操作：先删除 app/admin，再复制 src 内容
   rm -rf app/admin
   cp -r vendor/zoujingli/think-plugs-admin/src/* app/admin/

   为什么先删除？

   • 确保代码完全同步，避免旧文件残留
   • 使用 ! 前缀表示绝对复制模式
   • 适合需要完全覆盖的场景

2. 复制数据库迁移文件

   # 自动执行
   vendor/zoujingli/think-plugs-admin/stc/database/* → database/migrations/

3. 复制静态资源文件（如果有配置）

   # 自动执行
   vendor/zoujingli/think-plugs-admin/stc/public/* → public/static/

4. 清理原安装目录

   # 因为配置了 "clear": true
   rm -rf vendor/zoujingli/think-plugs-admin/

   为什么清理？

   • 代码已经复制到 app 目录，vendor 中的代码不再需要
   • 减少项目体积，避免代码重复
   • 明确表示这是模块插件，不是普通插件

步骤3：安装后的目录结构

安装完成后，项目结构如下：

项目根目录/
  ├── app/
  │   └── admin/              # 插件代码已复制到这里（可以自由修改）
  │       ├── controller/      # 控制器目录
  │       │   ├── Index.php    # 后台首页控制器
  │       │   ├── User.php     # 用户管理控制器
  │       │   └── ...
  │       ├── model/           # 模型目录
  │       │   ├── SystemUser.php
  │       │   └── ...
  │       ├── view/            # 视图目录
  │       │   ├── index/
  │       │   └── ...
  │       ├── Service.php      # 服务类（已注册）
  │       └── ...
  ├── database/
  │   └── migrations/          # 数据库迁移文件已复制到这里
  │       └── 20241010000001_install_admin20241010.php
  ├── vendor/                  # 原插件目录已被清理（clear: true）
  └── composer.json

步骤4：验证安装

安装完成后，可以通过以下方式验证：

# 1. 检查应用目录
ls -la app/admin/

# 2. 检查数据库迁移文件
ls -la database/migrations/

# 3. 检查 vendor 目录（应该已经被清理）
ls -la vendor/zoujingli/  # 应该看不到 think-plugs-admin 目录

# 4. 访问后台验证
# 浏览器访问：http://yourdomain.com/admin

步骤5：代码修改

模块插件的代码在 app 目录下，可以像应用代码一样自由修改：

<?php
// app/admin/controller/User.php
// 可以自由修改这个文件，不受插件更新影响

namespace app\admin\controller;

use think\admin\Controller;

class User extends Controller
{
    // 可以添加自定义方法
    public function customMethod()
    {
        // 自定义逻辑
    }
    
    // 可以修改原有方法
    public function index()
    {
        // 修改后的逻辑
    }
}

步骤6：卸载插件

模块插件的卸载需要手动操作：

# 1. 卸载 Composer 包（不会删除 app 目录下的代码）
composer remove zoujingli/think-plugs-admin

# 2. 手动删除应用目录下的代码
rm -rf app/admin

# 3. 手动清理数据库表（通过数据库管理工具或命令行）
# 方式1：使用数据库管理工具（如 phpMyAdmin）
# 方式2：使用命令行
php think migrate:rollback -t 20241010000001

# 4. 手动清理配置文件（如果有）
# 检查 config/ 目录下是否有插件相关的配置文件

卸载注意事项：

• ⚠️ 数据备份：卸载前请备份数据库，避免数据丢失
• ⚠️ 代码备份：如果修改了插件代码，请先备份
• ⚠️ 依赖检查：确保没有其他模块依赖此插件

⚙️ 配置说明

通过 composer.json 的 extra.plugin 配置插件安装行为，这是控制插件安装过程的核心配置。

配置项详细说明：

init - 初始化文件配置

用于在安装时创建初始化文件，如果文件已存在则不操作。

使用场景：

• 创建默认配置文件
• 创建初始化数据文件
• 创建必要的目录结构

配置示例：

{
  "plugin": {
    "init": {
      "config/plugin.php": "<?php return [];",  // 创建默认配置文件
      "data/init.json": "{}"                      // 创建初始化数据文件
    }
  }
}

工作原理：

1. 检查目标文件是否存在
2. 如果不存在，创建文件并写入内容
3. 如果已存在，跳过操作（保护用户自定义配置）

copy - 文件复制配置

定义安装时需要复制的文件和目录，支持两种复制模式。

复制模式对比：

模式1：增量复制（默认）

如果目标文件已存在则跳过，不会覆盖已有文件。

{
  "plugin": {
    "copy": {
      "stc/database": "database/migrations"  // 增量复制
    }
  }
}

工作原理：

# 安装时执行
if [ ! -f "database/migrations/xxx.php" ]; then
    cp vendor/plugin/stc/database/xxx.php database/migrations/
fi

适用场景：

• 数据库迁移文件（通常不会冲突）
• 静态资源文件（可以增量添加）
• 配置文件模板（用户可能已修改）

模式2：绝对复制（使用 ! 前缀）

先删除目标目录，再复制源目录内容，确保完全同步。

{
  "plugin": {
    "copy": {
      "src": "!app/admin"  // 绝对复制：先删除 app/admin，再复制 src 内容
    }
  }
}

工作原理：

# 安装时执行
rm -rf app/admin              # 先删除目标目录
cp -r vendor/plugin/src/* app/admin/  # 再复制源目录内容

适用场景：

• 模块插件代码（需要完全同步）
• 需要完全覆盖的目录
• 确保代码一致性的场景

⚠️ 注意事项：

• 绝对复制会删除目标目录的所有内容
• 如果目标目录有自定义文件，会被删除
• 建议仅在模块插件中使用

clear - 清理原安装目录

安装后是否清理 vendor 中的插件目录。

配置示例：

{
  "plugin": {
    "clear": true  // 安装后清理原安装目录
  }
}

工作原理：

# 安装完成后执行
if [ "$clear" == "true" ]; then
    rm -rf vendor/zoujingli/think-plugs-admin/
fi

适用场景：

• 模块插件（代码已复制到 app 目录）
• 减少项目体积
• 明确表示这是模块插件

⚠️ 注意事项：

• 清理后无法通过 composer update 更新插件
• 需要重新安装才能更新
• 仅推荐在模块插件中使用

event - 安装/卸载事件

定义安装和卸载时执行的事件处理类。

配置示例：

{
  "plugin": {
    "event": "plugin\\account\\InstallEvent"
  }
}

事件类实现：

<?php
namespace plugin\account;

class InstallEvent
{
    /**
     * 安装时执行
     */
    public static function onInstall(): void
    {
        // 创建必要的目录
        mkdir(syspath('runtime/account'), 0755, true);
        
        // 初始化配置
        sysconf('account.enabled', true);
        
        // 执行其他初始化操作
    }
    
    /**
     * 卸载时执行
     */
    public static function onRemove(): void
    {
        // 清理临时文件
        // 删除配置项
        // 执行其他清理操作
    }
}

忽略机制：

如果目标目录存在 ignore 文件，则跳过该复制操作。

使用场景：

• 用户不想覆盖某些文件
• 保护用户自定义配置
• 跳过某些目录的复制

示例：

# 在目标目录创建 ignore 文件
touch database/migrations/.ignore

# 安装时会跳过该目录的复制操作

📋 完整配置示例

📦 普通插件配置

普通插件保留在 vendor 目录，只复制必要的数据库迁移文件和静态资源：

{
  "type": "think-admin-plugin",
  "name": "zoujingli/think-plugs-account",
  "description": "Account Plugin for ThinkAdmin",
  "require": {
    "php": ">7.1",
    "zoujingli/think-library": "^6.1|@dev"
  },
  "autoload": {
    "psr-4": {
      "plugin\\account\\": "src"
    }
  },
  "extra": {
    "think": {
      "services": [
        "plugin\\account\\Service"
      ]
    },
    "plugin": {
      "copy": {
        "stc/database": "database/migrations"  // 只复制数据库迁移文件
      }
    }
  }
}

说明：

• 代码保留在 vendor/plugin/account/ 目录
• 只复制数据库迁移文件到 database/migrations
• 通过 autoload 自动加载插件类
• 卸载时只需 composer remove，不会影响 app 目录

🔧 模块插件配置

模块插件复制到 app 目录，安装后自动清理原安装目录：

{
  "type": "think-admin-plugin",
  "name": "zoujingli/think-plugs-admin",
  "description": "Admin Plugin for ThinkAdmin",
  "require": {
    "php": ">7.1",
    "zoujingli/think-library": "^6.1|@dev"
  },
  "autoload": {
    "psr-4": {
      "app\\admin\\": "src"  // 注意：命名空间指向 app\admin
    }
  },
  "extra": {
    "think": {
      "services": [
        "app\\admin\\Service"
      ]
    },
    "plugin": {
      "copy": {
        "src": "!app/admin",  // 绝对复制：先删除 app/admin，再复制
        "stc/database": "database/migrations"
      },
      "clear": true  // 安装后清理原安装目录
    }
  }
}

说明：

• 代码复制到 app/admin/ 目录（可以自定义修改）
• 使用 ! 前缀表示绝对复制（先删除再复制）
• clear: true 表示安装后清理 vendor 中的插件目录
• 卸载时需要手动删除 app/admin 目录

🔧 安装命令

标准安装

安装插件前，建议先更新所有组件，确保依赖关系正确：

# 更新所有组件
composer update --optimize-autoloader

# 安装插件
composer require zoujingli/think-plugs-admin

安装过程：

• Composer 会自动下载插件到 vendor 目录
• 安装器会自动执行 extra.plugin 配置的复制操作
• 插件服务类会自动注册到系统

开发版本安装

如果需要安装开发版本（通常包含最新功能，但可能不稳定）：

# 安装开发版本
composer require zoujingli/think-plugs-admin dev-master

# 或者指定分支
composer require zoujingli/think-plugs-admin dev-develop

注意事项：

• 开发版本可能包含未完成的功能
• 建议仅在开发环境使用
• 生产环境应使用稳定版本

插件卸载

卸载插件时，需要注意不同类型插件的处理方式：

普通插件卸载：

# 卸载插件（不会删除数据库表和配置文件）
composer remove zoujingli/think-plugs-account

# 手动清理（如果需要）
# - 删除数据库表（通过数据库管理工具）
# - 删除配置文件（如果有）
# - 删除静态资源（如果有）

模块插件卸载：

# 1. 卸载 Composer 包（不会删除 app 目录下的代码）
composer remove zoujingli/think-plugs-admin

# 2. 手动删除应用目录下的代码
rm -rf app/admin

# 3. 手动清理数据库和配置文件
# - 删除数据库表
# - 删除配置文件
# - 删除静态资源

卸载注意事项：

• 卸载前请备份重要数据
• 数据库表需要手动删除（避免数据丢失）
• 配置文件建议保留备份