---
url: /docs/5.0/plugin/faq.md
---
# 常见问题

> 本文总结了插件开发和使用过程中常见的问题及解决方案。

# 插件开发

## 安装相关

### Q: 修改了插件代码后没有生效？

**原因**：插件的路由、配置等文件需要重新安装才能加载。

**解决方案**：

```shell
# 先卸载
composer remove your/plugin --ignore-platform-reqs

# 再安装
composer require your/plugin:* --ignore-platform-reqs
```

### Q: 安装时提示版本不满足 minimum-stability？

**原因**：本地开发的包默认被视为 `dev` 版本，而项目可能要求 `stable`。

**解决方案**：在 `composer.json` 的 `repositories` 中指定版本：

```json
{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/*/*",
            "options": {
                "versions": {
                    "your/plugin": "1.0.0"
                }
            }
        }
    ]
}
```

### Q: 安装后路由 404？

**可能原因**：

1. 路由文件未放在 `routes/` 目录
2. 插件未正确安装
3. 路由文件命名不是 `api.php`

**解决方案**：

1. 确保路由文件位于 `your-plugin/routes/api.php`
2. 重新安装插件
3. 检查路由前缀是否正确

## 钩子相关

### Q: afterInstall 钩子没有执行？

**可能原因**：

1. 钩子文件名不正确
2. 类名不正确
3. 方法名拼写错误

**正确配置**：

* 文件名：`hook.php`（小写）
* 类名：`Hook`（首字母大写）
* 方法名：`afterInstall`（驼峰命名）

```php
// hook.php
<?php

class Hook
{
    public function afterInstall(array $context): void
    {
        // 你的代码
    }
}
```

### Q: afterUninstall 钩子无法访问插件文件？

**原因**：卸载后，vendor 目录下的插件链接已被删除。

**说明**：系统会在卸载前预加载 Hook 类，因此 `afterUninstall` 仍然可以执行。但此时无法 `require` 插件的其他文件。

**建议**：在 `beforeUninstall` 中加载需要的依赖，或将清理逻辑放在 `afterUninstall` 中直接执行。

### Q: 钩子中无法使用 Laravel 功能（如数据库、配置）？

**原因**：早期版本中，`before*` 钩子可能在 Laravel 启动前执行。

**现状**：当前版本已优化，所有钩子都在 Laravel 启动后执行，可以正常使用：

* Eloquent 模型
* `config()` 函数
* `Artisan::call()`
* 数据库操作

## 菜单相关

### Q: 创建的菜单不显示？

**可能原因**：

1. `module` 参数填写错误
2. 菜单类型设置错误
3. 未重新登录刷新权限

**解决方案**：

1. 确保 `module` 使用插件的根命名空间（如 `Test\Test`）
2. 检查 `type` 参数：1=目录，2=菜单，3=按钮
3. 清除浏览器缓存并重新登录

### Q: 卸载后菜单没有删除？

**原因**：`afterUninstall` 钩子中没有添加删除菜单的代码。

**解决方案**：

```php
public function afterUninstall(array $context): void
{
    Permissions::where('module', $context['namespace'])->delete();
}
```

### Q: 菜单图标不显示？

**原因**：图标名称不正确或使用了不存在的图标。

**解决方案**：

1. 访问 [Heroicons](https://heroicons.com/) 确认图标名称
2. 只填写图标名称，不需要前缀
3. 使用中划线命名，如 `cog-6-tooth`

## 视图相关

### Q: Vue 页面访问返回 404？

**可能原因**：

1. 视图文件路径不正确
2. 插件未安装
3. URL 格式错误

**正确的 URL 格式**：

```
http://127.0.0.1:8000/api/plugins/{vendor}/{plugin}/{path}
```

例如：`api/plugins/test/test/users/index`

对应文件：`your-plugin/resource/views/users/index.vue`

### Q: Plugin::view() 生成的路径不对？

**用法说明**：

```php
// 正确用法
Plugin::view('test/test', 'users.index');
// 输出: api/plugins/test/test/users/index

// 点号会自动转换为斜杠
Plugin::view('test/test', 'users.edit');
// 输出: api/plugins/test/test/users/edit
```

## 命名空间相关

### Q: 移动模型后报类找不到？

**原因**：移动文件后没有修改命名空间。

**解决方案**：确保命名空间与目录结构匹配：

```php
// 文件位置: packages/test/test/src/Models/User.php
namespace Test\Test\Models;  // 正确

// 错误示例
namespace App\Models;  // 错误！
```

### Q: PSR-4 自动加载不生效？

**检查步骤**：

1. 确认 `composer.json` 中的 `autoload` 配置正确
2. 运行 `composer dump-autoload`
3. 重新安装插件

```json
{
    "autoload": {
        "psr-4": {
            "Test\\Test\\": "src/"
        }
    }
}
```

## 数据库相关

### Q: 迁移文件找不到？

**原因**：`--path` 参数使用了错误的路径格式。

**正确用法**：

```shell
# Windows
php artisan migrate --path=packages\test\test\migrations

# Linux/Mac
php artisan migrate --path=packages/test/test/migrations
```

### Q: 如何在钩子中执行迁移？

```php
public function afterInstall(array $context): void
{
    Plugin::migrate($context['path'] . '/migrations');
}
```

## 开发建议

### 开发流程推荐

1. **修改代码** → 不需要重新安装
2. **修改路由/配置** → 需要重新安装
3. **修改 composer.json** → 需要重新安装
4. **修改钩子** → 需要重新安装并重新触发

### 调试技巧

1. **查看日志**：`storage/logs/laravel.log`
2. **使用 dd()** ：在控制器中调试
3. **Tinker 测试**：`php artisan tinker`

### 版本管理

* 开发阶段使用 `*` 版本约束
* 发布时指定具体版本号
* 遵循语义化版本规范

# 插件使用

## 安装插件

### Q: 如何安装插件？

从 CatchAdmin 插件市场下载的插件，解压后放到 `packages/` 目录，然后执行：

```shell
composer require vendor/plugin-name:* --ignore-platform-reqs
```

### Q: 安装插件后功能不生效？

**解决方案**：

1. 清除缓存：`php artisan cache:clear`
2. 重新登录后台
3. 检查菜单权限是否已分配给当前角色

### Q: 如何更新插件？

```shell
# 先卸载旧版本
composer remove vendor/plugin-name --ignore-platform-reqs

# 替换新版本文件到 packages/ 目录

# 重新安装
composer require vendor/plugin-name:* --ignore-platform-reqs
```

## 卸载插件

### Q: 如何卸载插件？

```shell
composer remove vendor/plugin-name --ignore-platform-reqs
```

### Q: 卸载后数据还在？

**说明**：插件卸载默认只删除代码，不会删除数据库数据。

**如需清理数据**：

1. 手动删除相关数据表
2. 或在插件的 `afterUninstall` 钩子中添加数据清理逻辑

## 还有问题？

如果以上内容没有解决你的问题，可以：

* 查看 [快速入门](./quickstart.md) 确认基础配置
* 查看 [插件开发实战](./practice.md) 了解完整流程