配置体系

Pin 的配置加载器位于 Pin\Bootstrap\LoadConfiguration。它扩展 Laravel 默认配置加载流程，让包内默认配置和业务项目配置可以递归合并。

加载顺序

使用 Pin\Application 时，配置加载顺序如下：

先加载 Pin 包内 config/*.php。
再加载业务项目 config/*.php，同名 key 会递归覆盖。
读取 config/config.{env}.php 作为环境覆盖。
单元测试场景会优先使用 config/config.testing.php。
调用 Application::loadedConfiguration() 钩子。

递归合并意味着业务项目可以只覆盖某一小段配置，而不必复制整份配置文件。

环境覆盖

环境配置文件按当前 app.env 选择，例如：

php

// config/config.production.php
return [
    'logging' => [
        'response' => [
            'enabled' => false,
        ],
    ],
];

测试环境中的 Pin\Testing\Application 会在没有 database.connections.testing 时自动补一个 SQLite 内存库。

应用配置

config/app.php 中 Pin 关注两个部分：

php

return [
    'frontend_domains' => explode(
        ',',
        env('FRONTEND_DOMAINS', parse_url(env('APP_URL', 'http://localhost'), PHP_URL_HOST))
    ),

    'x_api_document' => [
        'enabled' => env('APP_ENV') !== 'production',
        'allows' => ['Apifox', 'Scramble', 'docs/api'],
    ],
];

frontend_domains 用于判断请求是否来自受信任前端。
x_api_document 用于识别接口文档或调试工具来源。

常用环境变量

变量	说明
`FRONTEND_DOMAINS`	允许下发 CSRF Cookie 的前端来源域名
`X_API_DOCUMENT_ALLOWS`	API 文档调试来源标识
`DEFAULT_PAGE_SIZE`	默认分页大小
`AVAILABLE_PAGE_SIZES`	允许的分页大小列表
`LOG_SQL_ENABLED`	是否记录 SQL 日志
`LOG_RESPONSE_ENABLED`	是否记录 API 响应日志
`LOG_RESPONSE_MAX_LENGTH`	响应日志最大长度
`LOG_STACK_TRACT_ENABLED`	是否记录堆栈；当前配置键名保留代码中的拼写
`CAPTCHA_CACHE_ENABLED`	验证码是否启用一次性缓存
`FAKE_RESPONSE_ENABLED`	Action Fake Response 是否启用

配置覆盖建议

业务项目只需要创建同名配置文件并写入要覆盖的片段：

php

// config/pagination.php
return [
    'default_page_size' => 30,
    'available_page_sizes' => [30, 50, 100],
];

Pin 会将它和包内默认值递归合并。

配置缓存

配置缓存开启后，Laravel 不会重新扫描配置文件。修改配置后需要重新生成：

bash

php artisan config:clear
php artisan config:cache

配置体系 ​

加载顺序 ​

环境覆盖 ​

应用配置 ​

常用环境变量 ​

配置覆盖建议 ​

配置缓存 ​