配置

简介

Laravel 框架的所有配置文件都存放在 config 目录中。每个选项都有文档说明，欢迎浏览这些文件并熟悉可用选项。

这些配置文件可用于配置数据库连接、邮件服务器信息，以及应用 URL、加密密钥等其他核心配置值。

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 文件。安装过程中，该文件会自动复制为 .env。

Laravel 默认的 .env 文件包含一些常见配置值，这些值可能因应用在本地还是生产 Web 服务器上运行而不同。config 目录中的配置文件会通过 Laravel 的 env 函数读取这些值。

若与团队一起开发，可能希望继续在应用中包含并更新 .env.example 文件。在示例配置文件中放入占位值，团队中的其他开发者就能清楚看到运行应用需要哪些环境变量。

INFO

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

环境文件安全

不应将 .env 文件提交到应用的版本控制中，因为每位开发者 / 每台服务器可能需要不同的环境配置。此外，若入侵者获得源码仓库访问权限，敏感凭据就会暴露，从而带来安全风险。

不过，你可使用 Laravel 内置的环境加密来加密环境文件。加密后的环境文件可安全地放入版本控制。

额外的环境文件

在加载应用环境变量之前，Laravel 会判断是否已从外部提供 APP_ENV 环境变量，或是否指定了 --env CLI 参数。若是，Laravel 会尝试加载存在的 .env.[APP_ENV] 文件；若不存在，则加载默认的 .env 文件。

环境变量类型

.env 文件中的所有变量通常都会解析为字符串，因此提供了一些保留值，以便 env() 函数能返回更丰富的类型：

.env Value	env() Value
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' => (bool) 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...
}

INFO

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

加密环境文件

未加密的环境文件绝不应存入版本控制。不过，Laravel 允许你加密环境文件，从而可与应用其他部分一起安全地加入版本控制。

加密

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

php artisan env:encrypt

运行 env:encrypt 会加密 .env 文件，并将加密内容写入 .env.encrypted。解密密钥会显示在命令输出中，应存放在安全的密码管理器中。若希望自行提供加密密钥，可在调用命令时使用 --key 选项：

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

INFO

所提供密钥的长度应与所用加密算法要求的密钥长度一致。默认情况下，Laravel 使用需要 32 字符密钥的 AES-256-CBC 算法。你也可在调用命令时传入 --cipher 选项，使用 Laravel 加密器 支持的任意算法。

若应用有多个环境文件，例如 .env 与 .env.staging，可通过 --env 选项指定要加密的环境名称：

php artisan env:encrypt --env=staging

可读的变量名

加密环境文件时，可使用 --readable 选项在加密值的同时保留可见的变量名：

php artisan env:encrypt --readable

这将生成如下格式的加密文件：

APP_NAME=eyJpdiI6...
APP_ENV=eyJpdiI6...
APP_KEY=eyJpdiI6...
APP_DEBUG=eyJpdiI6...
APP_URL=eyJpdiI6...

使用可读格式可在不暴露敏感数据的情况下查看存在哪些环境变量。这也让审阅 pull request 更容易，因为无需解密即可看到哪些变量被添加、移除或重命名。

解密环境文件时，Laravel 会自动检测所用格式，因此 env:decrypt 命令无需额外选项。

INFO

使用 --readable 选项时，原始环境文件中的注释与空行不会包含在加密输出中。

解密

要解密环境文件，可使用 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::collection('config-key');

配置缓存

为提升应用速度，应使用 config:cache Artisan 命令将所有配置文件缓存为单个文件。这会将应用的所有配置选项合并为一个可由框架快速加载的文件。

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

配置被缓存后，框架在请求或 Artisan 命令期间将不再加载应用的 .env 文件；因此，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 实例。

要启用维护模式，执行 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 后，即可像未处于维护模式一样正常浏览应用。

INFO

维护模式密钥通常应由字母数字组成，可选地包含短横线。应避免使用 URL 中有特殊含义的字符，例如 ? 或 &。

多服务器上的维护模式

默认情况下，Laravel 使用基于文件的方式判断应用是否处于维护模式。这意味着要启用维护模式，必须在托管应用的每台服务器上执行 php artisan down。

或者，Laravel 提供基于缓存的维护模式处理方式。该方法只需在一台服务器上运行 php artisan down。要使用此方式，请修改应用 .env 中的维护模式变量。应选择所有服务器都能访问的缓存 store，以确保每台服务器上的维护模式状态一致：

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

预渲染维护模式视图

若在部署期间使用 php artisan down，用户在 Composer 依赖或其他基础设施组件更新时访问应用，仍可能偶尔遇到错误。这是因为框架需要启动相当一部分，才能判断应用处于维护模式，并用模板引擎渲染维护模式视图。

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

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

重定向维护模式请求

处于维护模式时，Laravel 会对用户尝试访问的所有应用 URL 显示维护模式视图。若需要，可指示 Laravel 将所有请求重定向到特定 URL，使用 redirect 选项即可。例如，可将所有请求重定向到 / URI：

php artisan down --redirect=/

禁用维护模式

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

php artisan up

INFO

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

维护模式与队列

应用处于维护模式时，不会处理任何队列任务。退出维护模式后，任务将恢复正常处理。

维护模式的替代方案

由于维护模式需要应用停机数秒，可考虑在 Laravel Cloud 这类全托管平台上运行应用，以实现 Laravel 的零停机部署。