配置

• 介绍
• 环境配置
  • 环境变量类型
  • 读取环境配置
  • 判断当前环境
• 访问配置值
• 配置缓存
• 调试模式
• 维护模式

介绍

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

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

环境配置

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

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

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

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

{tip} .env 文件中的任何变量都可以被外部环境变量覆盖，例如服务器级或系统级环境变量。

env 文件的安全

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

附加env文件

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

环境变量类型

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

如果你需要定义一个含有空格的环境变量，你可以用双引号括住这个值:

APP_NAME="My Application"

读取环境配置

当您的应用程序收到请求时，此文件中列出的所有变量都将加载到 $_ENV PHP 超级全局变量中。 但是，您可以使用 env f辅助函数从配置文件中的这些变量中读取值。 事实上，如果你查看 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')) {
    // The environment is local
}
 
if (App::environment(['local', 'staging'])) {
    // The environment is either local OR staging...
}

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

访问配置值

您可以在应用程序的任何位置使用全局 config 辅助函数轻松访问配置值。 可以使用"."语法访问配置值，其中包括您希望访问的文件名和选项。 也可以指定默认值，如果配置选项不存在，将返回:

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

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

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

配置缓存

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

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

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

调试模式

在你的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 选项来指定维护模式绕过token：

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

将应用程序设置为维护模式后，您可以导航到与此token匹配的应用程序 URL，Laravel 将向您的浏览器发出维护模式绕过 cookie:

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

访问此隐藏路由时，您将被重定向到应用程序的 / 路由。 将 cookie 发送到您的浏览器后，您将能够正常浏览应用程序，就好像您未开启维护模式一样。

{tip} 您的维护模式密码通常应由字母数字字符和短划线（可选）组成。 您应该避免在 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

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

维护模式和队列

当您的应用程序处于维护模式时，不会处理任何 队列任务。 一旦应用程序退出维护模式，队列将继续正常处理。

维护模式的替代方案

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