配置

• 介绍
• 环境配置
  • 环境变量类型
  • 检索环境配置
  • 确定当前环境
  • 加密环境文件
• 访问配置值
• 配置缓存
• 配置发布
• 调试模式
• 维护模式

介绍

Laravel框架的所有配置文件都存储在 config 目录中。每个选项都有文档说明，因此您可以随意查看这些文件，并熟悉可用的选项。
这些配置文件允许您配置数据库连接信息、邮件服务器信息以及各种其他核心配置值，例如应用程序时区和加密密钥。

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 文件，该文件定义了许多常见的环境变量。在 Laravel 安装过程中，该文件将自动复制为 .env。

learn小辉 翻译于 7小时前

0 重译

由 Trace92 审阅

Laravel 的默认 .env 文件包含一些常见的配置值，这些值可能会根据您的应用程序是在本地运行还是在生产 web 服务器上运行而有所不同。然后，这些值会被 config 目录中的配置文件通过 Laravel 的 env 函数读取。
如果您正在与团队一起开发，您可能希望继续在应用程序中包含和更新 .env.example 文件。通过在示例配置文件中放置占位符值，您的团队成员可以清楚地看到运行应用程序需要哪些环境变量。

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

环境文件安全性

您的 .env 文件不应提交到应用程序的源代码控制中，因为每个使用您的应用程序的开发者/服务器可能需要不同的环境配置。此外，如果入侵者获得了对您源代码控制仓库的访问权限，这将是一个安全风险，因为任何敏感的凭据都会被暴露。
然而，您可以使用 Laravel 内置的 环境加密 来加密您的环境文件。加密的环境文件可以安全地放置在源代码控制中。

附加环境文件

在加载应用程序的环境变量之前，Laravel 会确定是否外部提供了 APP_ENV 环境变量，或者是否指定了 --env CLI 参数。如果是这样，Laravel 将尝试加载存在的 .env.[APP_ENV] 文件。如果不存在，将加载默认的 .env 文件。

learn小辉 翻译于 7小时前

0 重译

由 Trace92 审阅

环境变量类型

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

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

APP_NAME="My Application"

检索环境配置

当应用程序收到请求时 .env 文件中列出的所有变量将被加载到 PHP 的超级全局变量 $_ENV 中。你可以使用 env 函数检索这些变量的值。实际上，如果你看过 Laravel 的配置文件，就能注意到有数个选项已经使用了这个函数：

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

env 函数的第二个参数是「默认值」。当没有找到对应环境变量时将返回 「默认值」。

获取当前环境配置

当前应用的环境配置是从你的.env 文件中的 APP_ENV 变量配置的。你可以通过 App facade 的 environment 函数获取：

use Illuminate\Support\Facades\App;

$environment = App::environment();

learn小辉 翻译于 7小时前

0 重译

由 Trace92 审阅

你还可以将参数传递给 environment 函数，以确定环境是否与给定值匹配。如果环境与任何给定值匹配，则该方法将返回 true

if (App::environment('local')) {
    // 本地环境
}

if (App::environment(['local', 'staging'])) {
    // 本地或临时环境...
}

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

加密环境文件

未加密的环境文件不应存储在源代码控制中。然而，Laravel 允许你加密你的环境文件，以便它们可以安全地添加到源代码控制中。

加密

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

php artisan env:encrypt

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

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

[!NOTE]
所提供的密钥的长度应该与所使用的加密密码所要求的密钥长度相匹配。默认情况下，Laravel 会使用 AES-256-CBC 密码，需要一个 32 个字符的密钥。你可以自由地使用 Laravel 的encrypter 所支持的任何密码，只要在调用该命令时传递 --cipher 选项即可

learn小辉 翻译于 7小时前

0 重译

由 Trace92 审阅

If your application has multiple environment files, such as .env and .env.staging, you may specify the environment file that should be encrypted by providing the environment name via the --env option:

php artisan env:encrypt --env=staging

Decryption

To decrypt an environment file, you may use the env:decrypt command. This command requires a decryption key, which Laravel will retrieve from the LARAVEL_ENV_ENCRYPTION_KEY environment variable:

php artisan env:decrypt

Or, the key may be provided directly to the command via the --key option:

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

When the env:decrypt command is invoked, Laravel will decrypt the contents of the .env.encrypted file and place the decrypted contents in the .env file.

The --cipher option may be provided to the env:decrypt command in order to use a custom encryption cipher:

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

If your application has multiple environment files, such as .env and .env.staging, you may specify the environment file that should be decrypted by providing the environment name via the --env option:

php artisan env:decrypt --env=staging

In order to overwrite an existing environment file, you may provide the --force option to the env:decrypt command:

php artisan env:decrypt --force

Accessing Configuration Values

You may easily access your configuration values using the Config facade or global config function from anywhere in your application. The configuration values may be accessed using "dot" syntax, which includes the name of the file and option you wish to access. A default value may also be specified and will be returned if the configuration option does not exist:

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');

To set configuration values at runtime, you may invoke the Config facade's set method or pass an array to the config function:

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

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

To assist with static analysis, the Config facade also provides typed configuration retrieval methods. If the retrieved configuration value does not match the expected type, an exception will be thrown:

Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');

Configuration Caching

To give your application a speed boost, you should cache all of your configuration files into a single file using the config:cache Artisan command. This will combine all of the configuration options for your application into a single file which can be quickly loaded by the framework.

You should typically run the php artisan config:cache command as part of your production deployment process. The command should not be run during local development as configuration options will frequently need to be changed during the course of your application's development.

Once the configuration has been cached, your application's .env file will not be loaded by the framework during requests or Artisan commands; therefore, the env function will only return external, system level environment variables.

For this reason, you should ensure you are only calling the env function from within your application's configuration (config) files. You can see many examples of this by examining Laravel's default configuration files. Configuration values may be accessed from anywhere in your application using the config function described above.

The config:clear command may be used to purge the cached configuration:

php artisan config:clear

[!WARNING]
If you execute the config:cache command during your deployment process, you should be sure that you are only calling the env function from within your configuration files. Once the configuration has been cached, the .env file will not be loaded; therefore, the env function will only return external, system level environment variables.

Configuration Publishing

Most of Laravel's configuration files are already published in your application's config directory; however, certain configuration files like cors.php and view.php are not published by default, as most applications will never need to modify them.

However, you may use the config:publish Artisan command to publish any configuration files that are not published by default:

php artisan config:publish

php artisan config:publish --all

Debug Mode

The debug option in your config/app.php configuration file determines how much information about an error is actually displayed to the user. By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.

[!WARNING]
For local development, you should set the APP_DEBUG environment variable to true. In your production environment, this value should always be false. If the variable is set to true in production, you risk exposing sensitive configuration values to your application's end users.

Maintenance Mode

When your application is in maintenance mode, a custom view will be displayed for all requests into your application. This makes it easy to "disable" your application while it is updating or when you are performing maintenance. A maintenance mode check is included in the default middleware stack for your application. If the application is in maintenance mode, a Symfony\Component\HttpKernel\Exception\HttpException instance will be thrown with a status code of 503.

To enable maintenance mode, execute the down Artisan command:

php artisan down

If you would like the Refresh HTTP header to be sent with all maintenance mode responses, you may provide the refresh option when invoking the down command. The Refresh header will instruct the browser to automatically refresh the page after the specified number of seconds:

php artisan down --refresh=15

You may also provide a retry option to the down command, which will be set as the Retry-After HTTP header's value, although browsers generally ignore this header:

php artisan down --retry=60

Bypassing Maintenance Mode

To allow maintenance mode to be bypassed using a secret token, you may use the secret option to specify a maintenance mode bypass token:

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

After placing the application in maintenance mode, you may navigate to the application URL matching this token and Laravel will issue a maintenance mode bypass cookie to your browser:

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

If you would like Laravel to generate the secret token for you, you may use the with-secret option. The secret will be displayed to you once the application is in maintenance mode:

php artisan down --with-secret

When accessing this hidden route, you will then be redirected to the / route of the application. Once the cookie has been issued to your browser, you will be able to browse the application normally as if it was not in maintenance mode.

[!NOTE]
Your maintenance mode secret should typically consist of alpha-numeric characters and, optionally, dashes. You should avoid using characters that have special meaning in URLs such as ? or &.

Maintenance Mode on Multiple Servers

By default, Laravel determines if your application is in maintenance mode using a file-based system. This means to activate maintenance mode, the php artisan down command has to be executed on each server hosting your application.

Alternatively, Laravel offers a cache-based method for handling maintenance mode. This method requires running the php artisan down command on just one server. To use this approach, modify the maintenance mode variables in your application's .env file. You should select a cache store that is accessible by all of your servers. This ensures the maintenance mode status is consistently maintained across every server:

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

Pre-Rendering the Maintenance Mode View

If you utilize the php artisan down command during deployment, your users may still occasionally encounter errors if they access the application while your Composer dependencies or other infrastructure components are updating. This occurs because a significant part of the Laravel framework must boot in order to determine your application is in maintenance mode and render the maintenance mode view using the templating engine.

For this reason, Laravel allows you to pre-render a maintenance mode view that will be returned at the very beginning of the request cycle. This view is rendered before any of your application's dependencies have loaded. You may pre-render a template of your choice using the down command's render option:

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

Redirecting Maintenance Mode Requests

While in maintenance mode, Laravel will display the maintenance mode view for all application URLs the user attempts to access. If you wish, you may instruct Laravel to redirect all requests to a specific URL. This may be accomplished using the redirect option. For example, you may wish to redirect all requests to the / URI:

php artisan down --redirect=/

Disabling Maintenance Mode

To disable maintenance mode, use the up command:

php artisan up

[!NOTE]
You may customize the default maintenance mode template by defining your own template at resources/views/errors/503.blade.php.

Maintenance Mode and Queues

While your application is in maintenance mode, no queued jobs will be handled. The jobs will continue to be handled as normal once the application is out of maintenance mode.

Alternatives to Maintenance Mode

Since maintenance mode requires your application to have several seconds of downtime, consider running your applications on a fully-managed platform like Laravel Cloud to accomplish zero-downtime deployment with Laravel.