配置

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

简介

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 文件及其应用。通过在示例配置文件中放入占位符值，团队中的其他开发人员可以清楚地看到运行应用程序所需的哪些环境变量。

环境文件安全性

你的 .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')) {
    // The environment is local
}
 
if (App::environment(['local', 'staging'])) {
    // The environment is either local OR staging...
}

加密环境文件

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

加密

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

php artisan env:encrypt

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

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

如果你的应用程序有多个环境文件，例如 .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');
 
// Retrieve a default value if the configuration value does not exist...
$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:cache Artisan 命令将所有配置文件缓存到单个文件中。这会将应用程序的所有配置选项合并到单个文件中，该文件可以由框架快速加载。

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

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

因此，您应该确保只从应用程序的配置（config）文件中调用 env 函数。您可以通过检查 Laravel 的默认配置文件来查看许多此类示例。配置值可以使用 上面描述的 config 函数从应用程序中的任何位置访问。

config:clear 命令可以用来清除缓存的配置。

php artisan config:clear

配置发布

大多数 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 文件中。

维护模式

当您的应用程序处于维护模式时，将为所有进入应用程序的请求显示自定义视图。这使得在应用程序更新或执行维护时“禁用”应用程序变得容易。应用程序的默认中间件堆栈中包含维护模式检查。如果应用程序处于维护模式，将抛出 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 发行到您的浏览器，您将能够像应用程序未处于维护模式一样正常浏览应用程序。

多台服务器上的维护模式

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

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

'maintenance' => [
    'driver' => 'cache',
    '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

维护模式和队列

当您的应用程序处于维护模式时，不会处理 排队作业。应用程序退出维护模式后，作业将继续正常处理。

维护模式的替代方法

由于维护模式要求您的应用程序停机几秒钟，请考虑使用 Laravel Vapor 和 Envoyer 等替代方法来实现 Laravel 的零停机部署。