配置 - Laravel 5.7 中文文档 - 文档

简介

Laravel 框架的所有配置文件都存储在 config 目录中。每个选项都有说明，您可以随时查看并熟悉可用选项。

环境配置

基于应用运行的环境使用不同的配置值通常是很有用的。例如，可能希望在本地服务器上使用与生产服务器不同的缓存驱动。

Laravel 利用 Vance Lucas 的 PHP 库 DotEnv 让此功能可以很容易实现。新安装的 Laravel 应用根目录包含一个 .env.example 文件。如果是使用 Composer 安装的 Laravel，该文件会自动改名为 .env。否则，您需要自己更改一下文件名。

.env 文件不应提交到应用的代码版本控制中，因为每个使用应用的开发者／服务器可能需要不同的环境配置。此外，当黑客获得代码仓库访问权时，这也会成为一个安全隐患，因为所有敏感数据都泄露了。

团队开发中，可能还希望应用中包含 .env.example 文件。可以将占位值放在示例配置文件中，这样团队的其他开发者就可以清楚地看到运行应用所需的环境变量。同样可以创建一个 .env.testing 文件，当运行 PHPUnit 测试或执行 Artisan 命令并添加 --env=testing 选项时，此文件中的值将覆盖 .env 文件中的。

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

环境变量类型

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

`.env` 值	`env()` 值
true	(bool) true
(true)	(bool) true
false	(bool) false
(false)	(bool) false
empty	(string) ''
(empty)	(string) ''
null	(null) null
(null)	(null) null

如果定义的环境变量的值含有空格，应将其放在双引号中：

APP_NAME="My Application"

获取环境配置

当应用收到请求时，.env 文件中列出的所有变量将被加载到 PHP 的超全局变量 $ _ENV 中。可以使用 env 函数来获取这些变量的值。实际上，如果查看 Laravel 的配置文件，就会注意到有些选项已经使用了该函数：

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

传递给 env 函数的第二个参数是「默认值」。如果环境变量中给定的键不存在，则会使用此默认值。

确定当前环境

当前应用环境通过 .env 文件里的 APP_ENV 变量决定。可以使用 App Facade 的 environment 方法来获取该值：

$environment = App::environment();

也可以传递参数给 environment 方法，检查当前环境是否和给定值匹配。如果与给定的任意值匹配，该方法将返回 true：

if (App::environment('local')) {
    // 当前环境是 local
}

if (App::environment(['local', 'staging'])) {
    // 当前环境是 local 或 staging
}

应用的环境变量会被服务器的 APP_ENV 环境变量所覆盖。通常在为同一应用配置不同环境时很有用，您可以在服务器配置中为给定的主机设置与之相匹配的环境。

调试页面隐藏环境变量

当应用抛出异常并且 APP_DEBUG 环境变量值为 true 时，调试页面会显示所有环境变量。如果某些情况下，需要隐藏部分变量，可以更新 config/app.php 文件中的 debug_blacklist 选项。

一些变量在环境变量和服务器变量中都可用。因此，需要将它们添加到 $_ENV 和 $_SERVER 两者的黑名单中：

return [

    // ...

    'debug_blacklist' => [
        '_ENV' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_SERVER' => [
            'APP_KEY',
            'DB_PASSWORD',
        ],

        '_POST' => [
            'password',
        ],
    ],
];

获取配置值

可以在应用的任何地方使用全局辅助函数 config 获取配置值。获取配置值可以使用「点」语法，包含要获取的文件名和选项。还可以为其指定默认值，如果要获取的配置项不存在，则返回此默认值：

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

要在运行时设置配置值，可以传递一个数组给 config 辅助函数：

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

缓存配置

为了提升应用速度，应该使用 Artisan 命令 config:cache 将所有配置文件缓存到单个文件中。合并所有配置项到单个文件后，该文件会被框架快速加载。

通常应该把运行 php artisan config:cache 命令作为生产环境部署的一部分。该命令不应在本地开发环境下运行，因为配置项在应用开发过程中经常需要更改。

如果部署过程中执行 config:cache 命令，应该确保只在配置文件里调用 env 函数。配置缓存后，不会加载 .env 文件，并且所有 env 函数调用都会返回 null。

维护模式

当应用处于维护模式时，所有对应用的请求都将显示一个自定义页面。这样在更新或维护应用时就可以轻松地「关闭」应用。维护模式检查包含在应用默认的中间件栈中。如果应用处于维护模式，将抛出一个状态码为 503 的 MaintenanceModeException 异常。

启用维护模式，可以执行 Artisan 命令 down：

php artisan down

也可以为 down 命令添加 --message 和 --retry 选项。--message 值用于显示或记录自定义信息，而 --retry 值将被设置为 HTTP 请求头 Retry-After 的值：

php artisan down --message="Upgrading Database" --retry=60

甚至还可以使用 --allow 选项指定允许访问应用的 IP 地址或网段：

php artisan down --allow=127.0.0.1 --allow=192.168.0.0/16

关闭维护模式，可以使用 up 命令：

php artisan up

可以通过修改默认维护模式的模板文件 resources/views/errors/503.blade.php 定义自己的模板。

维护模式 & 队列

当应用处于维护模式时，不会处理队列任务。这些任务会在应用退出维护模式后再继续处理。

维护模式的替代方案

由于维护模式会导致应用有数秒的停机时间，因此您可以考虑使用像 Envoyer 这样的替代方案，让 Laravel 完成零停机时间部署。