配置

介绍

Laravel 框架的所有配置文件都存储在 config 目录中。每个选项都有文档记录，因此请随意查看文件并熟悉可用的选项。

这些配置文件允许您配置诸如数据库连接信息、邮件服务器信息以及各种其他核心配置值（例如应用程序时区和加密密钥）之类的事项。

应用概述

匆忙之间？您可以通过 about Artisan 命令快速了解应用程序的配置、驱动程序和环境：

php artisan about

如果您只对应用程序概述输出的特定部分感兴趣，则可以使用 --only 选项过滤该部分：

php artisan about --only=environment

环境配置

根据应用程序运行的环境有不同的配置值通常很有帮助。例如，您可能希望在本地使用不同的缓存驱动程序，而在生产服务器上则使用另一个。

为了让这变得轻而易举，Laravel 使用了 DotEnv PHP 库。在全新的 Laravel 安装中，应用程序的根目录将包含一个 .env.example 文件，其中定义了许多常见的环境变量。在 Laravel 安装过程中，此文件将自动复制到 .env。

Laravel 的默认 .env 文件包含一些常见的配置值，这些值可能基于应用程序是在本地运行还是在生产 Web 服务器上运行而有所不同。这些值随后将使用 Laravel 的 env 函数从位于 config 目录内的各个 Laravel 配置文件中检索。

如果您与团队合作开发，可能希望继续将 .env.example 文件与应用程序一起包含。通过在示例配置文件中放置占位符值，您团队中的其他开发人员可以清楚地看到运行应用程序所需的环境变量。

您的 .env 文件中的任何变量都可以被外部环境变量（例如服务器级别或系统级别的环境变量）覆盖。

环境文件安全

您的 .env 文件不应该提交到应用程序的源代码控制中，因为使用您的应用程序的每个开发人员/服务器都可能需要不同的环境配置。此外，如果入侵者获取了您的源代码控制存储库的访问权限，这将是一种安全风险，因为任何敏感凭据都将被曝光。

但是，可以使用 Laravel 的内置环境加密对环境文件进行加密。加密的环境文件可以安全地放置在源代码控制中。

其他环境文件

在加载应用程序的环境变量之前，Laravel 会确定是否已经提供了 APP_ENV 环境变量或者是否已经指定了 --env CLI 参数。如果是这样，Laravel 将尝试加载 .env.[APP_ENV] 文件（如果存在）。如果不存在，则将加载默认的 .env 文件。

环境变量类型

您的 .env 文件中的所有变量通常都被解析为字符串，因此已创建了一些保留值，以允许您从 env() 函数返回更广泛的类型：

您需要定义一个包含空格的值的环境变量，可以将该值用双引号括起来：

APP_NAME="My Application"

检索环境配置

当您的应用程序接收到请求时，.env 文件中列出的所有变量将加载到 $_ENV PHP 超全局变量中。但是，您可以在配置文件中使用 env 函数从这些变量中检索值。事实上，如果您查看 Laravel 配置文件，您会注意到许多选项已经在使用此函数：

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

传递给 env 函数的第二个值是“默认值”。如果给定键的环境变量不存在，则将返回此值。

确定当前环境

当前应用程序环境通过您的 .env 文件中的 APP_ENV 变量确定。您可以通过 App 门面上的 environment 方法访问此值：

use Illuminate\Support\Facades\App;

$environment = App::environment();

您也可以向 environment 方法传递参数，以确定环境是否匹配给定值。如果环境与任何给定值匹配，则该方法将返回 true：

if (App::environment('local')) { 
    // 环境是本地的 
}

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

当前应用程序环境检测可以通过定义服务器级别的 APP_ENV 环境变量来覆盖。

加密环境文件

未加密的环境文件不应该存储在源代码控制中。但是，Laravel 允许您加密环境文件，以便它们可以安全地与您的应用程序的其余部分一起添加到源代码控制中。

加密

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

php artisan env:encrypt

运行 env:encrypt 命令将加密您的 .env 文件，并将加密后的内容放置在 .env.encrypted 文件中。解密密钥显示在命令输出中，应将其存储在安全的密码管理器中。如果您想要提供自己的加密密钥，则可以在调用命令时使用 --key 选项：

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

提供的密钥长度应与所使用的加密密码所需的密钥长度相匹配。默认情况下，Laravel 将使用 AES-256-CBC 密码，该密码需要 32 个字符的密钥。您可以通过在调用命令时传递 --cipher 选项来使用 Laravel 加密器支持的任何密码。

如果您的应用程序有多个环境文件，例如 .env 和 .env.staging，则可以通过使用 --env 选项提供环境名称来指定应加密的环境文件：

php artisan env:encrypt --env=staging

解密

要解密环境文件，可以使用 env:decrypt 命令。此命令需要解密密钥，Laravel 将从 LARAVEL_ENV_ENCRYPTION_KEY 环境变量中检索该密钥：

php artisan env:decrypt

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

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

当调用 env:decrypt 命令时，Laravel 将解密 .env.encrypted 文件的内容，并将解密后的内容放置在 .env 文件中。

可以通过 --cipher 选项向 env:decrypt 命令提供自定义加密密码：

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

如果您的应用程序有多个环境文件，例如 .env 和 .env.staging，则可以通过使用 --env 选项提供环境名称来指定应解密的环境文件：

php artisan env:decrypt --env=staging

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

php artisan env:decrypt --force

访问配置值

您可以在应用程序的任何位置使用全局的 config 函数轻松访问您的配置值。可以使用“点”语法访问配置值，其中包括您希望访问的文件名和选项名称。如果配置选项不存在，则还可以指定默认值，并返回该值：

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

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

要在运行时设置配置值，请将数组传递给 config 函数：

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

配置缓存

为了使您的应用程序加速，您应该使用 config:cache Artisan 命令将所有的配置文件缓存到一个单独的文件中。这将把应用程序的所有配置选项合并到一个文件中，框架可以快速加载该文件。

通常，您应该将 php artisan config:cache 命令作为生产部署过程的一部分运行。在本地开发过程中不应运行该命令，因为配置选项在应用程序开发过程中经常需要更改。

如果您在部署过程中执行了 config:cache 命令，则应确保仅在配置文件中从 env 函数中调用它。一旦配置已被缓存，.env 文件将不会被加载；因此，env 函数将仅返回外部的、系统级别的环境变量。

调试模式

您在 config/app.php 配置文件中的 debug 选项决定了有关错误信息的显示程度。默认情况下，此选项设置为尊重 APP_DEBUG 环境变量的值，该变量存储在您的 .env 文件中。

在本地开发中，您应将 APP_DEBUG 环境变量设置为 true。在生产环境中，此值应始终为 false。如果在生产中将该变量设置为 true，您的敏感配置值有可能会暴露给您的应用程序最终用户。

维护模式 当您的应用程序处于维护模式时，将为您的应用程序中的所有请求显示自定义视图。这使得在更新或执行维护时“禁用”您的应用程序变得非常容易。维护模式检查已包含在您的应用程序的默认中间件堆栈中。如果应用程序处于维护模式，将抛出 Symfony\Component\HttpKernel\Exception\HttpException 实例，并返回状态代码 503。

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

php artisan down

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

php artisan down --refresh=15

您还可以为 down 命令提供重试选项，该选项将被设置为 Retry-After HTTP 标头的值，尽管浏览器通常会忽略此标头：

php artisan down --retry=60

绕过维护模式

为了允许使用秘密令牌绕过维护模式，您可以使用 secret 选项指定一个维护模式绕过令牌：

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

将应用程序放在维护模式后，您可以导航到与此令牌匹配的应用程序 URL，Laravel 将向您的浏览器发出一个维护模式绕过 cookie：

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

当访问此隐藏路由时，您将被重定向到应用程序的 / 路由。一旦 cookie 已被发放到您的浏览器中，您就可以像维护模式不存在一样正常浏览应用程序。

您的维护模式 secret 通常应由字母数字字符和可选的破折号组成。应避免使用 URL 中具有特殊含义的字符，例如 ?。

预渲染维护模式视图

在部署期间，如果使用 php artisan down 命令，用户仍然可能在更新 Composer 依赖或其他基础架构组件时访问应用程序而偶尔遇到错误。这是因为 Laravel 框架的重要部分必须启动才能确定您的应用程序是否处于维护模式，并使用模板引擎呈现维护模式视图。

因此，Laravel 允许您预渲染维护模式视图，该视图将在请求周期的最开始返回。在加载应用程序的任何依赖项之前，此视图将呈现。您可以使用 down 命令的 render 选项预先呈现所选模板：

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

维护模式请求重定向

在维护模式下，Laravel 将为用户尝试访问的所有应用程序 URL 显示维护模式视图。如果愿意，您可以指示 Laravel 将所有请求重定向到特定的 URL。这可以使用 redirect 选项完成。例如，您可能希望将所有请求重定向到 / URI：

php artisan down --redirect=/

禁用维护模式

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

php artisan up

您可以通过在 resources/views/errors/503.blade.php 中定义自己的模板来自定义默认的维护模式模板。

维护模式和队列

在应用程序处于维护模式下时，将不会处理任何排队的作业。一旦应用程序退出维护模式，作业将像往常一样继续处理。

维护模式的替代方案

由于维护模式需要应用程序有几秒钟的停机时间，因此考虑使用 Laravel Vapor 和 Envoyer 等替代方案来实现 Laravel 的零停机时间部署。