CatchAdmin 常见问题

使用 CatchAdmin 过程中的常见问题和解决方案

响应格式不正确

如果你使用了类似 postman apifox 等等 api 管理工具，请求接口出现只输出一个字符串，而不是标准的后台响应结构的话。大概率是你缺少了头信息。你需要添加以下头信息

Request-From: Dashboard

依赖问题

由于 Laravel12 刚发布，CatchAdmin 的依赖可能无法正常安装。这通常是由于镜像更新慢导致的，建议取消使用镜像，直接从官方源下载。如果网络条件不佳，可以使用'魔法'工具(懂得吧)来提升下载速度。

镜像

这是目前维护中的可用的 composer 镜像，使用下面的命令安装

composer config -g repos.packagist composer https://packagist.pages.dev

路由未找到

遇到 CatchAdmin 路由访问问题时，首先检查路由是否存在：

php artisan route:list

如果接口路由不在路由表中，通常是因为相关模块未启用。请检查 storage/app/modules.json 文件中的模块状态，以权限模块为例：

{
  "title": "权限管理",
  "name": "permissions",
  "path": "permissions",
  "keywords": "权限, 角色, 部门",
  "description": "权限管理模块",
  "provider": "\\Modules\\Permissions\\Providers\\PermissionsServiceProvider",
  "version": "1.0.0",
  "enable": true // 该字段是否开启
}

模块路由命名重复

在 CatchAdmin 开发中，当多个模块存在同名控制器时可能出现路由冲突。例如 CMS 模块和 SHOP 模块都有名为 CategoryController 的控制器。正常情况下，通过路由分组就能解决：

// cms 分类路由
Route::prefix('cms')->group(function () {
    Route::apiResource('category', CategoryController::class);
});

// shop 分类路由
Route::prefix('shop')->group(function () {
    Route::apiResource('category', CategoryController::class);
});

但是这里会出现一个问题，当使用

php artisan route:cache

的时候，会提示一个错误

  Unable to prepare route [api/shop/category] for serialization. Another route has already been assigned name [category.index].

这个问题就是两个路由的 name 重复了, 无法进行缓存了。这里就需要设置成这样,只改 shop 的路由即可

// shop 分类路由
Route::prefix('shop')->group(function () {
    Route::apiResource('category', CategoryController::class)->names('shop_category')
});

打包出现报错

在构建 CatchAdmin 前端项目时，如果出现过多的 TypeScript 类型错误，但你对类型检查不太敏感，这些错误通常不会影响应用正常运行。

快速解决方法是修改 package.json 文件中的 build 命令，跳过类型检查：

{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build", 
    "build": "vite build", 
    "preview": "vite preview"
  }
}

Specified key was too long; max key length is 1000 bytes

SOLSTATE[42000]: Syntax error or access violation: 1071 Specified key was too long; max key length is 1000 bytes (...

如果安装的时候遇到这种错误，可以在使用下面的应急方案

app/Providers/AppServiceProvider.php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
// 添加这一行
use Illuminate\Support\Facades\Schema;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        //
    }

    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        // 添加这一行
        Schema::defaultStringLength(191);
    }
}