# 配置

- [简介](#introduction)
- [环境配置](#environment-configuration)
    - [环境变量类型](#environment-variable-types)
    - [获取环境配置](#retrieving-environment-configuration)
    - [确定当前环境](#determining-the-current-environment)
    - [加密环境文件](#encrypting-environment-files)
- [访问配置值](#accessing-configuration-values)
- [配置缓存](#configuration-caching)
- [配置发布](#configuration-publishing)
- [调试模式](#debug-mode)
- [维护模式](#maintenance-mode)

<a name="introduction"></a>
## 简介

Laravel 框架的所有配置文件都存储在 `config` 目录中。每个选项都有文档说明，因此你可以随意浏览这些文件，并熟悉可用的选项。

这些配置文件允许你配置如数据库连接信息、邮件服务器信息以及其他各种核心配置值，例如应用程序 URL 和加密密钥。

<a name="the-about-command"></a>
#### `about` 命令

Laravel 可以通过 `about` Artisan 命令显示应用配置、驱动和环境的概览信息。

```shell
php artisan about
```
如果你只对应用概览输出的某一特定部分感兴趣，可以使用 `--only` 选项进行筛选：

```shell
php artisan about --only=environment
```

或者，如果你想详细查看某个特定配置文件的值，可以使用 `config:show` Artisan 命令：

```shell
php artisan config:show database
```

<a name="environment-configuration"></a>

## 环境配置

根据应用运行环境的不同，使用不同的配置值通常非常有用。例如，你可能希望在本地环境中使用与生产服务器不同的缓存驱动。

为了简化这个过程，Laravel 使用了 [DotEnv](https://github.com/vlucas/phpdotenv) PHP 库。在全新的 Laravel 安装中，应用的根目录下会包含一个 `.env.example` 文件，该文件定义了许多常见的环境变量。在 Laravel 安装过程中，这个文件会自动复制为 `.env`。


Laravel 默认的 `.env` 文件包含一些常见配置值，这些值可能会根据应用运行在本地环境还是生产服务器上而有所不同。然后，`config` 目录下的配置文件将通过 Laravel 的 `env` 函数读取这些值。

如果你与团队一同开发，可能希望继续在应用中包含并更新 `.env.example` 文件。通过在示例配置文件中放置占位值，团队中的其他开发者可以清楚地了解运行应用所需的环境变量。

> [!NOTE]
> `.env` 文件中的任何变量都可以被外部环境变量（如服务器级别或系统级别的环境变量）所覆盖。

<a name="environment-file-security"></a>
#### 环境文件安全

你的 `.env` 文件不应提交到应用的版本控制中，因为每个使用该应用的开发者或服务器可能需要不同的环境配置。此外，如果入侵者获取了你的版本控制仓库的访问权限，这将是一个安全风险，因为任何敏感的凭据都会被暴露。

不过，你可以使用 Laravel 内置的 [环境加密](#encrypting-environment-files) 功能来加密你的环境文件。加密后的环境文件可以安全地放入版本控制中。

<a name="additional-environment-files"></a>
#### 附加环境文件

在加载应用的环境变量之前，Laravel 会判断是否已从外部提供了 `APP_ENV` 环境变量，或者是否指定了 `--env` CLI 参数。如果是，Laravel 将尝试加载对应的 `.env.[APP_ENV]` 文件（如果存在）。如果该文件不存在，则会加载默认的 `.env` 文件。



<a name="environment-variable-types"></a>
### 环境变量类型

`.env` 文件中的所有变量通常都会被解析为字符串，因此 Laravel 创建了一些保留值，让你能够通过 `env()` 函数返回更丰富的类型：

<div class="overflow-auto">

| `.env` 值 | `env()` 返回值 |
| ------------ | ------------- |
| true         | (bool) true   |
| (true)       | (bool) true   |
| false        | (bool) false  |
| (false)      | (bool) false  |
| empty        | (string) ''   |
| (empty)      | (string) ''   |
| null         | (null) null   |
| (null)       | (null) null   |

</div>


如果你需要使用包含空格的环境变量值，可以将该值用双引号括起来：

```ini
APP_NAME="My Application"
```

<a name="retrieving-environment-configuration"></a>
### 获取环境配置

当应用接收到请求时，`.env` 文件中列出的所有变量都会被加载到 PHP 超全局变量 `$_ENV` 中。不过，你可以使用 `env` 函数从这些变量中获取配置值。事实上，如果你查看 Laravel 的配置文件，会发现许多选项已经在使用这个函数：

```php
'debug' => (bool) env('APP_DEBUG', false),
```
`env` 函数的第二个参数是「默认值」。当没有找到对应环境变量时将返回 「默认值」。

<a name="determining-the-current-environment"></a>
### 确定当前环境

当前应用的环境通过 `.env` 文件中的 `APP_ENV` 变量来确定。你可以通过 `App` [facade](/docs/laravel/13.x/facades) 的 `environment` 函数获取：

```php
use Illuminate\Support\Facades\App;

$environment = App::environment();
```



你也可以向 `environment` 方法传递参数，以判断当前环境是否与指定值匹配。如果当前环境与任意给定的值匹配，该方法将返回 `true`：

```php
if (App::environment('local')) {
    // 当前环境为 local
}

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

> [!NOTE]
> 当前的应用程序环境检测可以通过定义服务器级别的 `APP_ENV` 环境变量进行覆盖。

<a name="encrypting-environment-files"></a>

### 加密环境文件

未加密的环境文件绝不应存储在版本控制中。不过，Laravel 允许你对环境文件进行加密，以便它们可以安全地随应用程序的其他部分一起添加到版本控制中。

<a name="encryption"></a>

#### 加密

要加密环境文件，你可以使用 `env:encrypt` 命令：

```shell
php artisan env:encrypt
```

运行 `env:encrypt` 命令将加密你的 `.env` 文件，并将加密后的内容放入 `.env.encrypted` 文件中。解密密钥将出现在命令的输出中，该密钥应存储在安全的密码管理器中。如果你想使用自己的加密密钥，可以在调用命令时使用 `--key` 选项：


```shell
php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
```

> [!NOTE]
> 提供的密钥长度必须与所使用的加密算法要求的密钥长度一致。默认情况下，Laravel 使用 `AES-256-CBC` 算法，该算法需要 32 个字符的密钥。你也可以在调用命令时通过 `--cipher` 选项使用 Laravel [加密器（encrypter）](/docs/laravel/13.x/encryption) 支持的任何加密算法。



如果你的应用程序有多个环境文件，如`.env` 和`.env.staging`，你可以通过 `--env` 选项提供环境名称来指定应该被加密的环境文件:

```shell
php artisan env:encrypt --env=staging
```

<a name="readable-variable-names"></a>
#### 可读变量名

在加密环境文件时，你可以使用 `--readable` 选项，让变量名保持可见，同时加密其值：

```shell
php artisan env:encrypt --readable
```

这将生成一个具有以下格式的加密文件：

```ini
APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...
```
使用可读格式，可以让你在不暴露敏感数据的情况下查看存在哪些环境变量。这也有助于更轻松地审查拉取请求（PR），因为你无需解密文件就可以看到添加、删除或重命名了哪些变量。

在解密环境文件时，Laravel 会自动检测使用的是哪种格式，因此 `env:decrypt` 命令无需额外指定选项。

> [!NOTE]
> 使用 `--readable` 选项时，原始环境文件中的注释和空行不会包含在加密输出中。

<a name="decryption"></a>
#### 解密

要解密环境文件，可以使用 `env:decrypt` 命令。该命令需要提供解密密钥，Laravel 会从 `LARAVEL_ENV_ENCRYPTION_KEY` 环境变量中获取该密钥：

```shell
php artisan env:decrypt
```

或者，也可以通过 `--key` 选项直接向命令提供密钥：

```shell
php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF
```

当执行 `env:decrypt` 命令时，Laravel 会解密 `.env.encrypted` 文件的内容，并将解密后的内容写入 `.env` 文件。



可以通过向 `env:decrypt` 命令提供 `--cipher` 选项，以使用自定义加密算法：

```shell
php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC
```

如果应用程序有多个环境文件（例如 `.env` 和 `.env.staging`），可以通过 `--env` 选项指定要解密的环境文件名：

```shell
php artisan env:decrypt --env=staging
```

为了覆盖现有的环境文件，可以为 `env:decrypt` 命令提供 `--force` 选项：

```shell
php artisan env:decrypt --force
```

<a name="accessing-configuration-values"></a>
## 访问配置值

你可以在应用程序的任何位置，通过 `Config` 门面或全局 `config` 函数轻松访问配置值。配置值可以使用「点」语法进行访问，其中包含你要访问的文件名和选项名。如果配置选项不存在，还可以指定默认值并返回：

```php
use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

$value = config('app.timezone');

//  如果配置值不存在，则检索默认值...
$value = config('app.timezone', 'Asia/Seoul');
```

要在运行时设置配置值，您可以调用 `Config` 门面的 `set` 方法，或向 `config` 函数传递一个数组：

```php
Config::set('app.timezone', 'America/Chicago');

config(['app.timezone' => 'America/Chicago']);
```

为便于静态分析，`Config` 门面还提供了类型化的配置值检索方法。如果检索到的配置值与预期类型不匹配，则会抛出异常：

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



<a name="configuration-caching"></a>
## 配置缓存

为了提升应用程序的速度，你应该使用 `config:cache` Artisan 命令将所有配置文件缓存到单个文件中。这会将应用程序的所有配置选项合并到一个文件中，以便框架能够快速加载。

通常情况下，你应该在生产部署流程中执行 `php artisan config:cache` 命令。该命令不应在本地开发期间运行，因为在开发过程中配置项会频繁变动。

一旦配置被缓存，应用程序的 `.env` 文件将不再被框架在请求或 Artisan 命令中加载；因此，`env` 函数只返回外部的系统级环境变量。

因此，应该确保只在应用程序的配置（`config`）文件中调用 `env` 函数。通过查看 Laravel 的默认配置文件，你可以看到许多这样的示例。配置值可以借助 `config` 函数从应用程序的任何位置访问，该函数的用法已在前述章节中介绍。

使用 `config:clear` 命令可以清除已缓存的配置：

```shell
php artisan config:clear
```

> [!WARNING]
> 如果在部署过程中执行了 `config:cache` 命令，请务必确保只在配置文件中调用 `env` 函数。一旦配置被缓存，`.env` 文件将不再被加载；因此，`env` 函数只会返回外部的系统级环境变量。

<a name="configuration-publishing"></a>
## 配置发布

Laravel 的大部分配置文件已经发布到应用程序的 `config` 目录中；然而，某些配置文件（如 `cors.php` 和 `view.php`）默认并未发布，因为大多数应用程序通常不需要修改它们。

不过，你可以使用 `config:publish` Artisan 命令来发布那些默认未发布的配置文件：

```shell
php artisan config:publish

php artisan config:publish --all
```

<a name="debug-mode"></a>
## 调试模式

`config/app.php` 配置文件中的 `debug` 选项决定了在发生错误时向用户显示多少信息。默认情况下，此选项设置遵循存储在 `.env` 文件中的 `APP_DEBUG` 环境变量的值。

> [!WARNING]
> 在本地开发环境中，应将 `APP_DEBUG` 环境变量设置为 `true`。**在生产环境中，该值必须始终为 `false`。如果在生产环境中将其设置为 `true`，则可能将敏感配置值暴露给应用程序的最终用户。**

<a name="maintenance-mode"></a>
## 维护模式

当应用程序处于维护模式时，所有请求都会显示一个自定义视图。这使得在应用程序更新或执行维护时能够轻松地「禁用」应用程序。维护模式检查已包含在应用程序的默认中间件堆栈中。如果应用程序处于维护模式，则会抛出一个状态码为 503 的 `Symfony\Component\HttpKernel\Exception\HttpException` 实例。

要启用维护模式，请执行 `down` Artisan 命令：

```shell
php artisan down
```



如果你希望在所有维护模式响应中发送 `Refresh` HTTP 标头，可以在调用 `down` 命令时提供 `refresh` 选项。`Refresh` 标头会指示浏览器在指定秒数后自动刷新页面：

```shell
php artisan down --refresh=15
```

你也可以为 `down` 命令提供 `retry` 选项，该选项将设置为 `Retry-After` HTTP 标头的值，不过浏览器通常会忽略此标头：

```shell
php artisan down --retry=60
```

<a name="bypassing-maintenance-mode"></a>
#### 绕过维护模式
即使在维护模式下，也可以使用 `secret` 选项指定一个维护模式绕过令牌：

```shell
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
```

在将应用程序置于维护模式后，你可以访问与此令牌匹配的应用程序 URL，Laravel 会向你的浏览器颁发一个维护模式绕过 Cookie：

```shell
https://example.com/1630542a-246b-4b66-afa1-dd72a4c43515
```

如果你希望 Laravel 为你生成密钥令牌，可以使用 `with-secret` 选项。应用程序进入维护模式后，密钥会显示给你：

```shell
php artisan down --with-secret
```

在访问这个隐藏路由后，你将被重定向到应用程序的 `/` 路由。一旦 Cookie 颁发到你的浏览器，你就可以像维护模式不存在一样正常浏览用程序。

> [!NOTE]
> 你的维护模式密钥通常应由字母数字字符组成，并可选地包含短横线。应避免使用在 URL 中具有特殊含义的字符，例如 `?` 或 `&`。


<a name="maintenance-mode-on-multiple-servers"></a>
#### 在多个服务器上使用维护模式

默认情况下，Laravel 使用基于文件的方式来判断应用程序是否处于维护模式。这意味着要激活维护模式，必须在托管应用程序的每台服务器上执行 `php artisan down` 命令。

此外，Laravel 还提供了一种基于缓存的维护模式处理方式。此方法只需在一台服务器上运行 `php artisan down` 命令即可。采用此方式时，需要修改应用程序 `.env` 文件中的维护模式配置变量。你应该选择一个所有服务器都能访问的缓存存储（`store`），以确保维护模式状态在所有服务器上保持一致：

```ini
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database
```

<a name="pre-rendering-the-maintenance-mode-view"></a>
#### 预渲染维护模式视图

如果在部署过程中使用 `php artisan down` 命令，当 Composer 依赖项或其他基础设施组件正在更新时，如果用户访问应用程序，他们可能仍然偶尔会遇到错误。这是因为 Laravel 框架需要启动相当一部分代码才能判断应用程序处于维护模式，并使用模板引擎渲染维护模式视图。

因此，Laravel 允许你预渲染一个维护模式视图，该视图将在请求周期的最开始阶段返回。此视图会在所有应用程序依赖项加载之前渲染。你可以使用 `down` 命令的 `render` 选项来预渲染自定义模板：

```shell
php artisan down --render="errors::503"
```

<a name="redirecting-maintenance-mode-requests"></a>
#### 重定向维护模式请求


在维护模式下，Laravel 会对用户尝试访问的所有应用 URL 显示维护模式视图。如果需要，你可以指示 Laravel 将所有请求重定向到特定的 URL。这可以通过 `redirect` 选项来实现。例如，你可能希望将所有请求重定向到 `/` URI：

```shell
php artisan down --redirect=/
```

<a name="disabling-maintenance-mode"></a>
#### 禁用维护模式

要禁用维护模式，请使用 `up` 命令：

```shell
php artisan up
```

> [!NOTE]
> 你可以通过在自己的 `resources/views/errors/503.blade.php` 文件中定义模板来自定义默认的维护模式模板。

<a name="maintenance-mode-queues"></a>
#### 维护模式与队列

当应用程序处于维护模式时，不会处理任何[队列任务](/docs/laravel/13.x/queues)。一旦应用程序退出维护模式，这些任务将继续正常处理。

<a name="alternatives-to-maintenance-mode"></a>

#### 维护模式的替代方案

由于维护模式需要应用程序有数秒的停机时间，请考虑在像 [Laravel Cloud](https://cloud.laravel.com) 这样的全托管平台上运行你的应用程序，以实现 Laravel 的零停机部署。
<a name="alternatives-to-maintenance-mode"></a>