配置

介绍

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

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

about 命令

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

php artisan about

如果你只对应用程序概览输出的某一部分感兴趣，可以使用 --only 选项进行过滤：

php artisan about --only=environment

或者，要详细查看某个配置文件的值，可以使用 config:show Artisan 命令：

php artisan config:show database

环境配置

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

为了解决这个问题，Laravel 使用了 DotEnv PHP 库。在一个全新的 Laravel 安装中，你的应用程序根目录将包含一个 .env.example 文件，定义了许多常见的环境变量。在 Laravel 安装过程中，这个文件会自动被复制到 .env。

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

如果你和团队一起开发，可能希望继续包含并更新 .env.example 文件。在示例配置文件中使用占位符值，其它团队开发者可以清楚地看到运行应用程序所需的环境变量。

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

环境文件安全

您的 .env 文件不应被提交到应用程序的源代码管理中，因为每个开发者/服务器可能需要不同的环境配置。此外，如果不小心将其提交，可能会导致安全风险，因为如果有入侵者访问了您的源代码库，任何敏感的凭证都会被暴露。

然而，您可以使用 Laravel 内置的 环境文件加密 功能来加密 .env 文件。加密后的环境文件可以安全地放入源代码管理中。

额外的环境文件

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

环境变量类型

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

.env 值 env() 值

true

(bool) true

(true)

(bool) true

false

(bool) false

(false)

(bool) false

empty

(string) ''

(empty)

(string) ''

null

(null) null

(null)

(null) null

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

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 字符的密钥。您可以自由使用任何 Laravel 的 加密器 支持的密码算法，通过在调用命令时传递 --cipher 选项。

如果您的应用程序有多个环境文件，例如 .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 facade 或全局 config 函数轻松地访问应用程序中的配置值。配置值可以使用 "点" 语法访问，语法包括文件名称和您要访问的选项。如果配置选项不存在，您还可以指定默认值，默认值将在此情况下返回：

use Illuminate\Support\Facades\Config;

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

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

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

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

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');

配置缓存

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

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

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

因此，您应该确保仅在应用程序的配置文件（config 文件）中调用 env 函数。通过检查 Laravel 的默认配置文件，您可以看到很多这样的例子。配置值可以使用上述 config 函数在应用程序的任何地方访问。

如果您需要清除已缓存的配置，可以使用 config:clear 命令：

php artisan config:clear

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

配置发布

Laravel 的大多数配置文件已经发布到应用程序的 config 目录中；然而，像 cors.php 和 view.php 这样的配置文件默认不会发布，因为大多数应用程序通常不需要修改它们。

不过，您可以使用 config:publish Artisan 命令来发布任何未默认发布的配置文件：

php artisan config:publish

php artisan config:publish --all

调试模式

在 config/app.php 配置文件中的 debug 选项决定了错误信息向用户展示的详细程度。默认情况下，这个选项会根据存储在 .env 文件中的 APP_DEBUG 环境变量的值来设置。

在本地开发环境中，您应该将 APP_DEBUG 环境变量设置为 true。在生产环境中，这个值应该始终设置为 false。如果在生产环境中将该变量设置为 true，您将面临暴露敏感配置值给应用程序最终用户的风险。

维护模式

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

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

php artisan down

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

php artisan down --refresh=15

您还可以向 down 命令提供 --retry 选项，该选项将被设置为 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

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

php artisan down --with-secret

访问这个隐藏的路由后，您将被重定向到应用程序的根路由 /。一旦 cookie 被发放到您的浏览器，您将能够像应用程序没有处于维护模式一样正常浏览它。

您的维护模式秘密令牌通常应包含字母数字字符，并可选择性地包含连字符。您应避免使用在 URL 中具有特殊意义的字符，如 ? 或 &。

多个服务器上的维护模式

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

另外，Laravel 提供了一种基于缓存的方法来处理维护模式。此方法只需在一个服务器上运行 php artisan down 命令。要使用这种方法，您需要在应用程序的 config/app.php 文件中修改 "driver" 设置为 cache。然后，选择一个所有服务器都可以访问的缓存存储。这确保了维护模式的状态在每个服务器之间始终保持一致：

'maintenance' => [
    'driver' => 'cache',
    'store' => 'database',
],

预渲染维护模式视图

如果在部署过程中使用 php artisan down 命令，用户在应用程序更新期间（例如 Composer 依赖项或其它基础设施组件更新时）可能仍会偶尔遇到错误。这是因为 Laravel 框架的一个重要部分必须启动，才能确定应用程序处于维护模式，并使用模板引擎呈现维护模式视图。

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

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

重定向维护模式请求

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

php artisan down --redirect=/

禁用维护模式

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

php artisan up

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

维护模式和队列

在您的应用处于维护模式时， 队列任务 将不会被处理。一旦应用退出维护模式，任务将会按正常方式处理。

维护模式的替代方案

由于维护模式会导致您的应用停机数秒，您可以考虑使用 Laravel Vapor 和 Envoyer 等工具，以实现零停机时间的部署。