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

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

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

NOTE

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

环境文件安全 ​

你的 .env 文件不应提交到应用的源代码管理中，因为使用你应用的每个开发者/服务器可能需要不同的环境配置。此外，如果入侵者获得了对源代码仓库的访问权限，这将构成安全风险，因为任何敏感凭证都会被暴露。

不过，可以使用 Laravel 内置的环境加密来加密你的环境文件。加密后的环境文件可以安全地放入源代码管理中。

额外的环境文件 ​

在加载应用的环境变量之前，Laravel 会确定是否已从外部提供了 APP_ENV 环境变量，或者是否指定了 --env CLI 参数。如果是，Laravel 将尝试加载 .env.[APP_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

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

ini
APP_NAME="My Application"

获取环境配置 ​

.env 文件中列出的所有变量在应用接收请求时都会被加载到 $_ENV PHP 超全局变量中。但是，你可以使用 env 函数在配置文件中获取这些变量的值。事实上，如果你查看 Laravel 的配置文件，会发现许多选项已经在使用此函数：

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

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

确定当前环境 ​

当前应用环境通过 .env 文件中的 APP_ENV 变量确定。你可以通过 App facade 上的 environment 方法访问此值：

php
use Illuminate\Support\Facades\App;

$environment = App::environment();

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

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

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

NOTE

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

加密环境文件 ​

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

加密 ​

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

shell
php artisan env:encrypt

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

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

NOTE

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

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

shell
php artisan env:encrypt --env=staging

可读变量名 ​

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

shell
php artisan env:encrypt --readable

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

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

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

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

NOTE

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

解密 ​

要解密环境文件，可以使用 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 facade 或全局 config 函数轻松访问配置值。配置值可以使用"点"语法访问，其中包括你要访问的文件名和选项名。还可以指定默认值，如果配置选项不存在则返回该默认值：

php
use Illuminate\Support\Facades\Config;

$value = Config::get('app.timezone');

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

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

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

php
Config::set('app.timezone', 'America/Chicago');

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

为了辅助静态分析，Config facade 还提供了类型化的配置获取方法。如果获取的配置值与预期类型不匹配，将抛出异常：

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

一旦配置被缓存，应用的 .env 文件在请求或 Artisan 命令期间将不会被框架加载；因此，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，你将面临向应用最终用户暴露敏感配置值的风险。

维护模式 ​

当应用处于维护模式时，所有进入应用的请求都将显示一个自定义视图。这使得在应用更新或执行维护时可以轻松"禁用"应用。维护模式检查包含在应用的默认 middleware 栈中。如果应用处于维护模式，将抛出状态码为 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 被发放到你的浏览器，你将能够像应用未处于维护模式一样正常浏览应用。

NOTE

维护模式密钥通常应由字母数字字符和可选的短横线组成。应避免使用在 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 框架的大部分必须启动才能确定应用处于维护模式并使用模板引擎渲染维护模式视图。

因此，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

NOTE

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

维护模式和队列 ​

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

维护模式的替代方案 ​

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