常见问题

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

插件开发

安装相关

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

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

解决方案：

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

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

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

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

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

{
    "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（驼峰命名）

// 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 钩子中没有添加删除菜单的代码。

解决方案：

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

Q: 菜单图标不显示？

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

解决方案：

1. 访问 Heroicons 确认图标名称
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() 生成的路径不对？

用法说明：

// 正确用法
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: 移动模型后报类找不到？

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

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

// 文件位置: 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. 重新安装插件

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

数据库相关

Q: 迁移文件找不到？

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

正确用法：

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

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

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

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/ 目录，然后执行：

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

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

解决方案：

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

Q: 如何更新插件？

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

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

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

卸载插件

Q: 如何卸载插件？

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

Q: 卸载后数据还在？

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

如需清理数据：

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

还有问题？

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

• 查看 快速入门 确认基础配置
• 查看 插件开发实战 了解完整流程