配置

• 介绍
• 环境配置
  • 环境变量类型
  • 检索环境配置
  • 确定当前环境
  • 加密环境文件
• 访问配置值
• 配置缓存
• 配置发布
• 调试模式
• 维护模式

介绍

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 文件包含一些常见的配置值，这些值可能会根据您的应用程序是在本地运行还是在生产 web 服务器上运行而有所不同。然后，这些值会被 config 目录中的配置文件通过 Laravel 的 env 函数读取。
如果您正在与团队一起开发，您可能希望继续在应用程序中包含和更新 .env.example 文件。通过在示例配置文件中放置占位符值，您的团队成员可以清楚地看到运行应用程序需要哪些环境变量。

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

环境文件安全性

您的 .env 文件不应提交到应用程序的源代码控制中，因为每个使用您的应用程序的开发者/服务器可能需要不同的环境配置。此外，如果入侵者获得了对您源代码控制仓库的访问权限，这将是一个安全风险，因为任何敏感的凭据都会被暴露。
然而，您可以使用 Laravel 内置的 环境加密 来加密您的环境文件。加密的环境文件可以安全地放置在源代码控制中。

附加环境文件

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

环境变量类型

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

如果需要使用包含空格的值定义环境变量，则可以通过将该值括在双引号中来实现

APP_NAME="My Application"

检索环境配置

当应用程序收到请求时 .env 文件中列出的所有变量将被加载到 PHP 的超级全局变量 $_ENV 中。你可以使用 env 函数检索这些变量的值。实际上，如果你看过 Laravel 的配置文件，就能注意到有数个选项已经使用了这个函数：

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

env 函数的第二个参数是「默认值」。当没有找到对应环境变量时将返回 「默认值」。

获取当前环境配置

当前应用的环境配置是从你的.env 文件中的 APP_ENV 变量配置的。你可以通过 App facade 的 environment 函数获取：

use Illuminate\Support\Facades\App;

$environment = App::environment();

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

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

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

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

加密环境文件

未加密的环境文件不应存储在源代码控制中。然而，Laravel 允许你加密你的环境文件，以便它们可以安全地添加到源代码控制中。

加密

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

php artisan env:encrypt

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

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

[!NOTE]
所提供的密钥的长度应该与所使用的加密密码所要求的密钥长度相匹配。默认情况下，Laravel 会使用 AES-256-CBC 密码，需要一个 32 个字符的密钥。你可以自由地使用 Laravel 的encrypter 所支持的任何密码，只要在调用该命令时传递 --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 文件中。
可以通过向 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 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

[!WARNING]
如果在部署过程中执行 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 环境变量的值。

[!WARNING]
对于本地开发，你应该将 APP_DEBUG 环境变量设置为 true。在生产环境中，这个值应该始终为 false。如果在生产中将变量设置为 true，你将冒着向应用程序的最终用户暴露敏感配置值的风险。

维护模式

当你的应用程序处于维护模式时，所有请求到你的应用程序的请求都会显示一个自定义视图。这使得在更新应用程序或进行维护时「禁用」你的应用程序变得很简单。维护模式检查包含在应用程序的默认中间件堆栈中。如果应用程序处于维护模式，将抛出一个带有 503 状态码的 Symfony\Component\HttpKernel\Exception\HttpException 实例。

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

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 被颁发到你的浏览器，你就可以像维护模式不存在一样正常浏览应用程序。

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

多服务器上的维护模式

默认情况下，Laravel 使用基于文件的系统来确定你的应用程序是否处于维护模式。这意味着要激活维护模式，需要在托管应用程序的每个服务器上执行 php artisan down 命令。
另外，Laravel 提供了一种基于缓存的维护模式处理方法。这种方法只需在一台服务器上运行 php artisan down 命令。要使用这种方法，请修改应用程序 config/app.php 文件中的 "driver" 设置为 cache。然后，选择一个所有服务器都可以访问的缓存 store。这样可以确保维护模式状态在每台服务器上保持一致：

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

预渲染维护模式视图

如果你在部署过程中使用 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 Cloud 这样的完全托管平台上运行你的应用程序，以使用 Laravel 实现零停机时间部署。

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/laravel/12.x/co...

译文地址：https://learnku.com/docs/laravel/12.x/co...