配置

简介

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

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

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 文件包含一些常见的配置值，这些值可能因应用程序是在本地运行还是在生产 Web 服务器上运行而有所不同。config 目录中的配置文件随后会通过 Laravel 的 env 函数读取这些值。

如果你与团队协作开发，可能希望持续在应用程序中包含并更新 .env.example 文件。通过在示例配置文件中设置占位值，团队中的其他开发者就能清楚了解运行应用程序所需的环境变量。

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

环境文件安全性

不应将你的 .env 文件提交到应用程序的源代码管理中，因为使用应用程序的每个开发者/服务器可能需要不同的环境配置。此外，如果入侵者获得了源代码管理仓库的访问权限，这会构成安全风险，因为任何敏感凭证都会被泄露。

不过，可以使用 Laravel 内置的环境加密功能对环境文件进行加密。加密后的环境文件可以安全地存放在源代码管理中。

额外的环境文件

在加载应用程序的环境变量之前，Laravel 会判断是否通过外部提供了 APP_ENV 环境变量，或者是否指定了 --env 命令行参数。如果是这样，Laravel 会尝试加载存在的 .env.[APP_ENV] 文件。若该文件不存在，则会加载默认的 .env 文件。

环境变量类型

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

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

APP_NAME="My Application"

检索环境配置

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

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

传递给 env 函数的第二个值是“默认值”。如果给定的键不存在对应的环境变量，就会返回该值。

确定当前环境

当前应用程序环境由 .env 文件中的 APP_ENV 变量决定。你可以通过 门面（facade） App 的 environment 方法访问该值：

use Illuminate\Support\Facades\App;

$environment = App::environment();

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

if (App::environment('local')) {
    // The environment is local
}

if (App::environment(['local', 'staging'])) {
    // The environment is either local OR 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 加密器（encrypter） 支持的任何加密算法。

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

php artisan env:encrypt --env=staging

可读的变量名

加密环境文件时，可以使用 --readable 选项，在加密变量值的同时保留可见的变量名：

php artisan env:encrypt --readable

这将生成具有如下格式的加密文件：

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

使用可读格式，你可以查看存在哪些环境变量，而不会暴露敏感数据。它还使得审查拉取请求变得容易得多，因为你可以查看添加、删除或重写了哪些变量，而无需解密文件。

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

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

更新可读的环境文件

更新可读的加密环境文件时，Laravel 会保留未更改的值，并移除源环境文件中不再存在的变量：

php artisan env:encrypt --readable --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

若加密文件不存在，则会创建该文件。更新现有文件时，请提供创建该文件时所用的相同加密密钥和加密算法。如果文件无法解密，命令将失败且不会覆盖该文件。

若要对所有值重新加密，请使用 --force 选项。这允许你更改加密密钥或替换无效的加密文件：

php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

解密

若要解密环境文件，你可以使用 env:decrypt 命令。该命令需要一个解密密钥，Laravel 将从 LARAVEL_ENV_ENCRYPTION_KEY 环境变量中获取该密钥：

php artisan env:decrypt

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

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

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

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 门面或全局 config 函数轻松访问配置值。配置值可以使用“点”语法进行访问，该语法包含你要访问的文件名称和选项名称。还可以指定一个默认值，当配置选项不存在时，将返回该默认值：

use Illuminate\Support\Facades\Config;

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

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

// 当配置值不存在时，获取默认值……
$value = config('app.timezone', 'Asia/Seoul');

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

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

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

为了辅助静态分析，Config 门面还提供了类型化的配置获取方法。如果获取到的配置值与预期类型不匹配，将抛出异常：

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

配置缓存

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

通常，你应该在生产环境部署过程中运行 php artisan config:cache 命令。该命令不应在本地开发过程中运行，因为在应用开发期间，往往需要频繁修改配置选项。

一旦配置被缓存，在请求或 Artisan 命令执行过程中，框架将不再加载应用的 .env 文件；因此，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 选项决定了实际向用户展示的关于错误的信息量。默认情况下，该选项设置为遵循 APP_DEBUG 环境变量的值，该环境变量存储在 .env 文件中。

在本地开发时，应将 APP_DEBUG 环境变量设置为 true。在生产环境中，该值应始终为 false。如果在生产环境中将该变量设置为 true，你将面临向应用终端用户泄露敏感配置值的风险。

维护模式

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

若要启用维护模式，请执行 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 命令。若要使用此方法，请修改应用 .env 文件中的维护模式变量。你应该选择一个所有服务器都能访问的缓存 store。这能确保在每台服务器上一致地维持维护模式状态：

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

预渲染维护模式视图

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

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

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

重定向维护模式请求

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

php artisan down --redirect=/

禁用维护模式

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

php artisan up

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

维护模式与队列

当应用程序处于维护模式时，不会处理 排队任务。一旦应用程序退出维护模式，任务将像往常一样继续处理。

维护模式的替代方案

由于维护模式会导致应用程序有几秒钟的停机时间，建议在完全托管的平台（如 Laravel Cloud）上运行应用程序，从而利用 Laravel 实现零停机部署。