---
url: /docs/5.0/plugin/commands.md
---
# Artisan 命令

> 本文介绍 CatchAdmin 插件系统提供的 Artisan 命令。

## 命令一览

| 命令 | 说明 |
|------|------|
| `catch:plugin-init` | 初始化一个新的插件项目 |
| `catch:plugin-install` | 安装插件系统 |
| `catch:plugin-pack` | 将插件打包为 zip 文件 |
| `plugin:optimize` | 优化插件记录 |
| `plugin:clear` | 清除插件记录文件 |

## catch:plugin-init

初始化一个新的插件项目，交互式创建插件骨架代码。

### 使用方法

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

### 交互流程

命令会依次询问以下信息：

| 输入项 | 说明 | 示例 |
|--------|------|------|
| 插件标题 | 插件的显示名称 | `我的插件` |
| 包名 | vendor/package 格式 | `catch/my-plugin` |
| 描述 | 插件功能描述 | `这是一个测试插件` |
| 版本号 | 语义化版本 | `1.0.0` |
| 作者 | 作者信息 | `张三 <zhangsan@example.com>` |
| PSR-4 命名空间路径 | 自动加载路径 | `src/` |

### 生成结果

命令执行后会在 `packages/` 目录下生成插件骨架：

```
packages/catch/my-plugin/
├─src/
├─hook.php
├─composer.json
└─README.md
```

:::tip 💡 提示

* 包名必须符合 `vendor/package` 格式
* 如果检测到 Git 配置，会自动填充作者信息
* 生成后需要执行 `composer require` 安装插件
  :::

## catch:plugin-install

安装插件系统，创建插件管理菜单。

### 使用方法

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

### 可选参数

| 参数 | 说明 |
|------|------|
| `--view` | 发布插件管理视图文件 |

### 功能说明

此命令会：

1. 发布插件管理视图（如果使用 `--view` 参数）
2. 创建「插件管理」后台菜单

:::warning ⚠️ 注意
此命令通常只需要在初次安装 CatchAdmin 时执行一次。
:::

## catch:plugin-pack

将插件打包为 zip 文件，用于发布或分发。

### 使用方法

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

### 交互流程

1. 列出所有可用插件
2. 选择要打包的插件
3. 自动打包并输出结果

### 输出示例

```
📦 CatchAdmin 插件打包
  插件: 测试插件
  版本: 1.0.0
  文件: 15 个
  大小: 12.5 KB
  输出: packages/.dist/test-test-1.0.0.zip
```

### 打包规则

* **输出目录**：`packages/.dist/`
* **文件命名**：`{包名}-{版本号}.zip`
* **排除文件**：根据 `config/plugin.php` 中的 `pack_excludes` 配置排除

### 配置排除文件

在 `config/plugin.php` 中配置：

```php
'pack_excludes' => [
    '.git',
    '.gitignore',
    'node_modules',
    'vendor',
    '.idea',
    '.vscode',
],
```

:::tip 💡 提示
打包前请确保：

* `composer.json` 中有正确的 `version` 字段
* 已清理不需要的临时文件
  :::

## plugin:optimize

扫描插件目录并更新插件记录文件。

### 使用方法

```shell
php artisan plugin:optimize
```

### 功能说明

此命令会：

1. 扫描 `packages/` 目录下所有已安装的插件
2. 读取每个插件的 `composer.json`
3. 更新 `storage/packages/plugins.json` 记录

### 使用场景

* 手动添加插件目录后同步记录
* 插件记录文件损坏后重建
* 批量更新插件版本信息

### 输出示例

```
优化完成，共 3 个插件
```

## plugin:clear

清除插件记录文件。

### 使用方法

```shell
php artisan plugin:clear
```

### 功能说明

删除 `storage/packages/plugins.json` 文件，清空所有插件安装记录。

:::warning ⚠️ 注意
此命令**不会删除插件文件**，只会清除记录。清除后可以使用 `plugin:optimize` 重建记录。
:::

### 输出示例

```
插件记录已清除
```

## 常用工作流

### 开发新插件

```shell
# 1. 初始化插件
php artisan catch:plugin-init

# 2. 安装插件
composer require vendor/package:* --ignore-platform-reqs

# 3. 开发...

# 4. 打包发布
php artisan catch:plugin-pack
```

### 修复插件记录

```shell
# 清除旧记录
php artisan plugin:clear

# 重新扫描
php artisan plugin:optimize
```