配置

简介

Hypervel 是一个类 Laravel 的 PHP 框架，支持原生协程，拥有超高性能。

Hypervel 借鉴了 Laravel 的许多核心组件，并保持了相似的使用方式，让 Laravel 开发者可以快速上手。它将 Laravel 优雅、表达力强的开发体验与基于协程的强大性能结合在一起。如果你熟悉 Laravel，几乎无需学习成本即可迁移。

这是构建微服务、API 网关以及高并发应用的理想选择——这些场景中传统 PHP 框架往往面临性能瓶颈。

为什么选择 Hypervel？

虽然 Laravel Octane 显著提升了 Laravel 应用的性能，但我们也需要认清现代 Web 应用的本质：多数延迟来自 I/O 操作，例如文件读写、数据库查询或 API 请求。

Laravel 并不支持协程——它整个框架的设计仍基于阻塞式 I/O。如果你的应用 I/O 操作密集，那么依旧会遇到性能瓶颈。比如：

想象你在开发一个 AI 聊天机器人，每次调用对话 API 都需要 3–5 秒响应。在 Laravel Octane 中，如果你配置了 10 个 worker 并同时收到 10 个请求，这些 worker 都会被阻塞直到响应返回。

你可以查看 Laravel Octane 和 Hypervel 的基准性能对比

即使 Laravel Octane 优化了性能，但并发处理能力仍然受限于 I/O 耗时。而 Hypervel 则通过协程机制解决了这个问题，可以在不阻塞 worker 的情况下并发执行多个 I/O 操作，从而显著提高 I/O 密集型应用的性能和吞吐能力。

查看这个相关讨论 issue

配置简介

Hypervel 的所有配置文件都位于 config 目录下。每个配置选项都有文档说明，你可以自由查看，了解有哪些可用选项。

这些配置文件允许你配置数据库连接、邮件服务器信息、应用 URL、加密密钥等核心参数。

about 命令

Hypervel 提供了 about Artisan 命令，可以快速查看应用的配置概况、驱动信息和运行环境。

php artisan about

如果你只关注某个部分，可以使用 --only 参数过滤：

php artisan about --only=environment

要查看某个配置文件的详细内容，可以使用 config:show 命令：

php artisan config:show database

不支持递归引用配置项

由于 Hypervel 在框架启动初期非常早地初始化了配置系统（与 Laravel 不同），因此在读取配置文件时，Config 实例尚未就绪，不能在配置文件中引用其他配置项。

例如，以下写法会导致报错：

return [
    'foo' => config('bar.title'),
];

⚠️ 警告：

某些特殊的配置文件，如 config/app.php、config/dependencies.php、config/annotations.php，会在应用容器尚未构建前加载。在这些文件中，请不要调用任何依赖容器的函数。

环境配置

在不同环境下（如本地、生产）使用不同的配置值是非常常见的做法。Hypervel 使用了 DotEnv 库来简化这一流程。

新安装的 Hypervel 应用中，根目录下会有一个 .env.example 文件，定义了一些常见的环境变量。在安装过程中，它会被复制为 .env 文件。

.env 文件中包含的变量，会在配置文件中通过 env 函数读取，并参与配置。

如果你在团队中协作开发，建议保留并维护 .env.example 文件，让其他开发者知道项目需要哪些环境变量。

说明：.env 文件中的变量可以被服务器或系统级环境变量覆盖。

环境变量的类型转换

.env 文件中的值默认都会被解析为字符串。为支持更丰富的类型，Hypervel 的 env() 函数支持以下特殊值：

如果你需要设置包含空格的值，请使用双引号包裹：

APP_NAME="My Application"

读取环境变量

你可以在配置文件中使用 env() 函数获取环境变量。例如：

'debug' => env('APP_DEBUG', false),

第二个参数是默认值——如果找不到对应环境变量，就返回这个默认值。

获取当前运行环境

当前运行环境是通过 .env 文件中的 APP_ENV 变量确定的。你可以通过 App facade 的 environment 方法访问：

use Hypervel\Support\Facades\App;
$env = App::environment();

也可以传入参数判断是否属于指定环境：

if (App::environment('local')) {
    // 当前是本地环境
}
if (App::environment(['local', 'staging'])) {
    // 当前环境是 local 或 staging
}

说明：你可以通过服务器级别的 APP_ENV 变量覆盖 .env 中的环境配置。

访问配置项

你可以通过 Config facade 或 config() 全局函数来访问配置项，支持 “点语法”（即 文件名.选项名）：

use Hypervel\Support\Facades\Config;
$value = Config::get('app.timezone');
$value = config('app.timezone');
// 若配置项不存在，返回默认值
$value = config('app.timezone', 'Asia/Seoul');

你也可以在运行时修改配置项：

Config::set('app.timezone', 'America/Chicago');
config(['app.timezone' => 'America/Chicago']);

为了提高类型安全，Config facade 还提供了带类型的方法。若返回值类型不符，会抛出异常：

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');

发布配置文件

Hypervel 默认已将大多数配置文件发布到 config 目录中。但像 cors.php 和 view.php 这类不是所有项目都会用到的配置文件默认不会发布。

你可以通过 Artisan 命令手动发布这些配置文件：

php artisan vendor:publish package
php artisan vendor:publish --all

调试模式

config/app.php 中的 debug 选项用于控制异常信息的展示范围。它的值默认通过 .env 文件中的 APP_DEBUG 环境变量控制。

⚠️ 在本地开发环境中，建议将 APP_DEBUG 设置为 true；而在生产环境中必须为 false，否则可能泄露敏感信息。