跳至内容

配置

介绍

Laravel 框架的所有配置文件都存储在该config目录中。每个选项都有文档记录，因此您可以随意浏览这些文件并熟悉可用的选项。

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

命令about​

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

1php artisan about

如果您只对应用程序概述输出的特定部分感兴趣，则可以使用以下选项过滤该部分--only：

1php artisan about --only=environment

或者，要详细探索特定配置文件的值，您可以使用config:showArtisan 命令：

1php 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环境变量是否由外部提供，或者--envCLI 参数是否已指定。如果已提供，Laravel 将尝试加载.env.[APP_ENV]文件（如果存在）。如果文件不存在，.env则加载默认文件。

环境变量类型

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

.env价值 env()价值
真的 （布尔值）真
（真的） （布尔值）真
错误的 （布尔值）false
（错误的） （布尔值）false
空的 （细绳） ''
（空的） （细绳） ''
无效的 （空） 空
（无效的） （空） 空

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

1APP_NAME="My Application"

检索环境配置

当你的应用程序收到请求时，文件中列出的所有变量.env都会被加载到PHP 超全局变量中。但是，你可以在配置文件中使用该函数来检索这些变量的值。事实上，如果你查看 Laravel 配置文件，你会注意到很多选项已经在使用这个函数：$_ENVenv

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

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

确定当前环境

APP_ENV当前应用环境由文件中的变量决定.env。你可以通过Facadeenvironment中的方法来访问这个值：App 

1use Illuminate\Support\Facades\App;
2 
3$environment = App::environment();

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

1if (App::environment('local')) {
2    // The environment is local
3}
4 
5if (App::environment(['local', 'staging'])) {
6    // The environment is either local OR staging...
7}

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

加密环境文件

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

加密

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

1php artisan env:encrypt

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

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

所提供密钥的长度应与所用加密算法所需的密钥长度匹配。默认情况下，Laravel 将使用AES-256-CBC需要 32 个字符密钥的加密算法。您可以通过在调用命令时传递选项来使用 Laravel加密器支持的任何加密算法。--cipher

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

1php artisan env:encrypt --env=staging

解密

要解密环境文件，可以使用以下env:decrypt命令。此命令需要解密密钥，Laravel 将从LARAVEL_ENV_ENCRYPTION_KEY环境变量中检索该密钥：

1php artisan env:decrypt

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

1php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

--cipher可以向命令提供选项以env:decrypt使用自定义加密密码：

1php artisan env:decrypt --key=qUWuNRdfuImXcKxZ --cipher=AES-128-CBC

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

1php artisan env:decrypt --env=staging

为了覆盖现有的环境文件，您可以--force为env:decrypt命令提供以下选项：

1php artisan env:decrypt --force

访问配置值

Config您可以在应用程序的任何位置使用Facade 或全局函数轻松访问配置值config。可以使用“点”语法访问配置值，该语法包含要访问的文件名和选项。还可以指定默认值，如果配置选项不存在，则返回默认值：

1use Illuminate\Support\Facades\Config;
2 
3$value = Config::get('app.timezone');
4 
5$value = config('app.timezone');
6 
7// Retrieve a default value if the configuration value does not exist...
8$value = config('app.timezone', 'Asia/Seoul');

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

1Config::set('app.timezone', 'America/Chicago');
2 
3config(['app.timezone' => 'America/Chicago']);

为了协助静态分析，Config外观模块还提供了类型化的配置检索方法。如果检索到的配置值与预期类型不匹配，则会抛出异常：

1Config::string('config-key');
2Config::integer('config-key');
3Config::float('config-key');
4Config::boolean('config-key');
5Config::array('config-key');

配置缓存

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

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

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

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

以下命令config:clear可用于清除缓存的配置：

1php artisan config:clear

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

配置发布

Laravel 的大部分配置文件已经发布在应用程序的config目录中；但是，某些配置文件（如cors.php和）view.php默认不会发布，因为大多数应用程序永远不需要修改它们。

但是，您可以使用config:publishArtisan 命令发布任何默认未发布的配置文件：

1php artisan config:publish
2 
3php artisan config:publish --all

调试模式

debug配置文件中的选项决定config/app.php了实际向用户显示多少有关错误的信息。默认情况下，此选项设置为遵循APP_DEBUG存储在.env文件中的环境变量的值。

对于本地开发，应将APP_DEBUG环境变量设置为true。在生产环境中，此值应始终为false。如果在生产环境中将变量设置为true，则可能会将敏感配置值暴露给应用程序的最终用户。

维护模式

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

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

1php artisan down

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

1php artisan down --refresh=15

您还可以为命令提供一个retry选项down，该选项将被设置为Retry-AfterHTTP 标头的值，尽管浏览器通常会忽略此标头：

1php artisan down --retry=60

绕过维护模式

要允许使用秘密令牌绕过维护模式，您可以使用该secret选项指定维护模式绕过令牌：

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

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

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

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

1php artisan down --with-secret

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

维护模式密钥通常应由字母数字字符以及（可选）短划线组成。应避免在 URL 中使用具有特殊含义的字符，例如?或&。

多台服务器上的维护模式

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

另外，Laravel 提供了一种基于缓存的方法来处理维护模式。此方法php artisan down只需在一台服务器上运行命令即可。要使用此方法，请修改应用程序.env文件中的维护模式变量。您应该选择一个所有服务器都可以访问的缓存store。这可确保维护模式状态在所有服务器上保持一致：

1APP_MAINTENANCE_DRIVER=cache
2APP_MAINTENANCE_STORE=database

预渲染维护模式视图

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

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

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

重定向维护模式请求

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

1php artisan down --redirect=/

禁用维护模式

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

1php artisan up

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

维护模式和队列

当您的应用程序处于维护模式时，队列中的任务将不会被处理。应用程序退出维护模式后，任务将继续照常处理。

维护模式的替代方案

由于维护模式要求您的应用程序有几秒钟的停机时间，请考虑在完全托管的平台（如Laravel Cloud）上运行您的应用程序，以使用 Laravel 实现零停机部署。