Laravel 中文文档

主题

全部文档

配置 ​

简介 ​

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

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

about 命令 ​

Laravel 可通过 about Artisan 命令展示应用配置、驱动与环境的概览。

shell
php artisan about

若只关心应用概览输出中的某一部分，可用 --only 选项过滤：

shell
php artisan about --only=environment

或者，若要详细查看某个配置文件的值，可使用 config:show Artisan 命令：

shell
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 Valueenv() Value
true(bool) true
(true)(bool) true
false(bool) false
(false)(bool) false
empty(string) ''
(empty)(string) ''
null(null) null
(null)(null) null

若需要定义包含空格的环境变量值，可用双引号将值括起来：

ini
APP_NAME="My Application"

获取环境配置 ​

应用收到请求时，.env 中列出的所有变量都会加载到 PHP 超全局变量 $_ENV 中。不过，你可在配置文件中使用 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...
}

INFO

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

加密环境文件 ​

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

加密 ​

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

shell
php artisan env:encrypt

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

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

INFO

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

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

shell
php artisan env:encrypt --env=staging

解密 ​

要解密环境文件，可使用 env:decrypt 命令。该命令需要解密密钥，Laravel 会从 LARAVEL_ENV_ENCRYPTION_KEY 环境变量获取：

shell
php artisan env:decrypt

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

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

调用 env:decrypt 时，Laravel 会解密 .env.encrypted 的内容，并将解密结果写入 .env 文件。

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

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

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

shell
php artisan env:decrypt --env=staging

若要覆盖已有环境文件，可向 env:decrypt 提供 --force 选项：

shell
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。本地开发期间不应运行该命令，因为开发过程中经常需要更改配置选项。

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

因此，应确保仅在应用的配置（config）文件中调用 env 函数。查看 Laravel 默认配置文件可以看到许多示例。配置值可在应用任意位置使用上文描述的 config 函数访问。

可使用 config:clear 命令清除缓存的配置：

shell
php artisan config:clear

WARNING

若在部署流程中执行 config:cache，请确保仅在配置文件中调用 env 函数。配置被缓存后，.env 文件将不会被加载；因此，env 函数只会返回外部系统级环境变量。

发布配置 ​

Laravel 的大多数配置文件已发布到应用的 config 目录；不过，像 cors.php 与 view.php 这类配置文件默认不会发布，因为大多数应用无需修改它们。

不过，你可使用 config:publish Artisan 命令发布默认未发布的任意配置文件：

shell
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 命令：

shell
php artisan down

若希望所有维护模式响应都发送 Refresh HTTP 头，可在调用 down 时提供 refresh 选项。Refresh 头会指示浏览器在指定秒数后自动刷新页面：

shell
php artisan down --refresh=15

也可向 down 命令提供 retry 选项，它会作为 Retry-After HTTP 头的值，不过浏览器通常会忽略该头：

shell
php artisan down --retry=60

绕过维护模式 ​

若允许使用密钥令牌绕过维护模式，可使用 secret 选项指定绕过令牌：

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

将应用置于维护模式后，可访问与该令牌匹配的应用 URL，Laravel 会向浏览器签发维护模式绕过 Cookie：

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

若希望 Laravel 为你生成密钥令牌，可使用 with-secret 选项。应用进入维护模式后会显示该密钥：

shell
php artisan down --with-secret

访问该隐藏路由后，你会被重定向到应用的 / 路由。浏览器获得 Cookie 后，即可像未处于维护模式一样正常浏览应用。

INFO

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

多服务器上的维护模式 ​

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

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

ini
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

预渲染维护模式视图 ​

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

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

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

重定向维护模式请求 ​

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

shell
php artisan down --redirect=/

禁用维护模式 ​

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

shell
php artisan up

INFO

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

维护模式与队列 ​

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

维护模式的替代方案 ​

由于维护模式需要应用停机数秒，可考虑使用 Laravel Vapor 与 Envoyer 等方案，以实现 Laravel 的零停机部署。