---
url: /docs/3.0/server/config.md
---
# CatchAdmin 配置详解

> 系统配置和模块配置的使用指南

CatchAdmin 提供了灵活的配置机制，支持系统级和模块级的配置管理。首先了解系统的核心配置文件：

```php title="config/catch.php"
return [
    /*
    |--------------------------------------------------------------------------
    | catch-admin super admin id
    |--------------------------------------------------------------------------
    |
    | where you can set super admin id
    |
    */
    'super_admin' => 1,

    /*
    |--------------------------------------------------------------------------
    | catch-admin module setting
    |--------------------------------------------------------------------------
    |
    | the root where module generate
    | the namespace is module root namespace
    | the default dirs is module generate default dirs
    */
    'module' => [
        'root' => 'modules',

        'namespace' => 'Modules',

        'default' => ['develop', 'user', 'permission'],

        'default_dirs' => [
            'Http'.DIRECTORY_SEPARATOR,

            'Http'.DIRECTORY_SEPARATOR.'Requests'.DIRECTORY_SEPARATOR,

            'Http'.DIRECTORY_SEPARATOR.'Controllers'.DIRECTORY_SEPARATOR,

            'Models'.DIRECTORY_SEPARATOR,

            'views'.DIRECTORY_SEPARATOR,
        ],

        // storage module information
        // which driver should be used?
        'driver' => [
            // currently, catchadmin support file and database
            // the default is driver
            'default' => 'file',

            // use database driver
            'table_name' => 'admin_modules'
        ],

        /**
         * module routes collection
         *
         */
        'routes' => [],
    ],

    /*
    |--------------------------------------------------------------------------
    | catch-admin response
    |--------------------------------------------------------------------------
    */
    'response' => [
        // it's a controller middleware, it's set in CatchController
        // if you not need json response, don't extend CatchController
        'always_json' => \Catch\Middleware\JsonResponseMiddleware::class,

        // response listener
        // it  listens [RequestHandled] event, if you don't need this
        // you can change this config
        'request_handled_listener' => \Catch\Listeners\RequestHandledListener::class
    ],

    /*
    |--------------------------------------------------------------------------
    | catch-admin auth setting
    |--------------------------------------------------------------------------
    */
    'auth' => [
        'guards' => [
            'admin' => [
                'driver' => 'jwt',
                'provider' => 'admin_users',
            ],
        ],

        'providers' => [
            'admin_users' => [
                'driver' => 'eloquent',
                'model' => \Modules\User\Models\User::class
            ]
        ]
    ],

    /*
   |--------------------------------------------------------------------------
   | database sql log
   |--------------------------------------------------------------------------
   */
    'listen_db_log' => true,

    /*
   |--------------------------------------------------------------------------
   | route config
   |--------------------------------------------------------------------------
   */
    'route' => [
        'prefix' => 'api',

        'middlewares' => [
            \Catch\Middleware\AuthMiddleware::class,
            \Catch\Middleware\JsonResponseMiddleware::class
        ]
    ],
];
```

## 配置项详解

### 超级管理员配置

* `super_admin`：设置超级管理员的用户 ID，默认为 1。超级管理员不受任何权限限制

### 模块系统配置

* `module` 模块相关的核心配置
  * `root`：模块存放的根目录，默认为 `modules`
  * `namespace`：模块的根命名空间，默认为 `Modules`
  * `default`：系统默认模块列表，包含 `develop`、`user`、`common` 三个基础模块
  * `default_dirs`：新建模块时自动生成的默认目录结构
  * `driver`：模块信息存储驱动，支持 `file` 和 `database` 两种方式
  * `routes`：模块路由集合配置

### 响应机制配置

* `response` API 响应相关配置
  * `always_json`：强制 JSON 响应输出的中间件
  * `request_handled_listener`：请求处理监听器，用于统一响应格式

### 认证系统配置

* `auth` 认证相关配置
  * `guards`：认证守卫配置，定义了 `admin` 守卫使用 JWT 驱动
  * `providers`：用户提供者配置，指定用户模型

### 开发调试配置

* `listen_db_log`：是否开启数据库 SQL 查询日志监听，便于开发调试

### 路由系统配置

* `route` 全局路由配置
  * `prefix`：API 路由前缀，默认为 `api`
  * `middlewares`：默认应用的中间件列表

:::tip 配置建议
项目有定制化需求时，优先检查这些配置选项，大多数需求可以通过配置调整来满足，无需修改源码。
:::

## 模块配置

除了系统级配置，CatchAdmin 还支持模块级的独立配置。每个模块的配置相互独立，互不影响，提高了模块的可移植性。

### 默认配置方式

模块需要配置时，直接在模块目录下创建 `config` 目录，系统会自动发现并加载配置文件：

```
modules/YourModule/
├── config/
│   ├── database.php
│   └── services.php
└── ...
```

### 自定义配置路径

如果需要自定义配置文件位置，可以在模块的服务提供者中重写 `configPath` 方法：

```php title="modules/Test/Providers/TestServiceProvider"
namespace Modules\Test\Providers;

use Catch\CatchAdmin;
use Catch\Providers\CatchModuleServiceProvider;

class TestServiceProvider extends CatchModuleServiceProvider
{
    public function confitPath(): string
    {
        return config_path;
    }
}
```

### 配置文件结构

以权限模块为例，典型的模块配置结构如下：

```
Permissions/
└── config/
    ├── database.php
    └── permissions.php
```

### 配置读取方式

模块配置的读取需要包含模块名称作为前缀：

```php
// 错误方式：直接读取配置文件名
config('database')  // ❌ 会读取系统的数据库配置

// 正确方式：模块名.配置文件名.配置键
config('permissions.database.connection')  // ✅ 读取权限模块的数据库配置
config('permissions.permissions.default_role')  // ✅ 读取权限模块的权限配置
```

### 配置命名规范

* **模块名**：使用小写，与模块目录名一致
* **配置文件名**：使用小写，语义明确
* **配置键名**：使用下划线命名法

这种设计避免了模块间配置冲突，同时保持了良好的命名空间隔离。