laravel_getting started_configuration_配置

Introduction - 介绍

All of the configuration files for the Laravel framework are stored in the config directory.

Each option is documented, so feel free to look through the files and get familiar with the options available to you.

These configuration files allow you to configure things like your database connection information, your mail server information, as well as various other core configuration values such as your application timezone and encryption key.

所有 Laravel 框架的配置文件都存储在 config 目录中。

每个选项都有 文档说明，所以请随意 查看文件 并熟悉可用的 选项。

这些 配置文件 允许你配置诸如 数据库连接信息、邮件服务器信息 以及其他各种核心配置数值，如 应用程序时区和加密密钥。

下图是database.php中的配置：

The about Command - about 命令

Laravel can display an overview of your application’s configuration, drivers, and environment via the about Artisan command.

通过 Laravel 的 about Artisan 命令，可以展示应用程序的 配置、驱动程序和环境的概述信息。

php artisan about

If you’re only interested in a particular section of the application overview output, you may filter for that section using the --only option:

php artisan about --only=environment

如果你只关注应用概述输出中的特定部分，可以使用 --only 选项进行筛选：

Or, to explore a specific configuration file's values in detail, you may use the config:show Artisan command:

或者，要详细查看特定配置文件的数值，可以使用 config:show Artisan 命令：

php artisan config:show database

Environment Configuration - 环境配置

It is often helpful to have different configuration values based on the environment where the application is running.

For example, you may wish to use a different cache driver locally than you do on your production server.

To make this a cinch, Laravel utilizes the DotEnv PHP library.

根据应用程序运行的环境，基于不同的配置数值常常非常有帮助。

例如，你可能希望在本地使用不同的缓存驱动程序，而在生产服务器上使用另一种。

为了使这个过程变得简单易行，Laravel 使用了 DotEnv PHP 库。

In a fresh Laravel installation, the root directory of your application will contain a .env.example file that defines many common environment variables.

在 新安装的 Laravel 中，你的应用程序根目录下会包含一个 .env.example 文件，其中定义了许多常见的环境变量。

During the Laravel installation process, this file will automatically be copied to .env.

在Laravel安装过程中，该文件将会被自动复制并命名为 .env。

Laravel’s default .env file contains some common configuration values that may differ based on whether your application is running locally or on a production web server.

Laravel 的默认 .env 文件包含了一些常见的配置数值，这些值可能会根据你的应用是在本地运行还是在生产 Web 服务器上运行而有所不同。

These values are then read by the configuration files within the config directory using Laravel’s env function.

If you are developing with a team, you may wish to continue including and updating the .env.example file with your application.

这些数值然后、通过 Laravel 的 env 函数、被 config 目录中的配置文件读取。

如果你正在与团队开发，你可能希望继续使用.env.example 文件、并随应用程序一起进行包含和更新。

By putting placeholder values in the example configuration file, other developers on your team can clearly see which environment variables are needed to run your application.

Any variable in your .env file can be overridden by external environment variables such as server-level or system-level environment variables.

通过在示例配置文件中放置占位符值，团队中其他开发人员可以清晰地看到运行应用程序所需的环境变量。

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

Environment File Security - 环境文件安全

Your .env file should not be committed to your application's source control, since each developer / server using your application could require a different environment configuration.

你的 .env 文件不应该提交到 应用程序的源代码控制中，因为使用你的应用程序的每个开发者/服务器可能需要不同的环境配置。

Furthermore, this would be a security risk in the event an intruder gains access to your source control repository, since any sensitive credentials would get exposed.

However, it is possible to encrypt you r environment file using Laravel’s built-in environment encryption.

Encrypted environment files may be placed in source control safely.

此外，如果黑客能够访问你的源代码控制存储库，这将是一个安全风险，因为任何敏感凭据都会被暴露。

然而，可以使用 Laravel 内置的 环境文件加密功能来加密你的环境文件。

加密的环境文件 可以安全地放在 源代码控制中。

Additional Environment Files - 额外的环境文件

Before loading your application's environment variables, Laravel determines if an APP_ENV environment variable has been externally provided or if the --env CLI argument has been specified.

If so, Laravel will attempt to load an .env.[APP_ENV] file if it exists.

If it does not exist, the default .env file will be loaded.

在加载应用程序的环境变量之前，Laravel会确定是否已外部提供了一个 APP_ENV 环境变量，或者是否已指定了 --env CLI 参数。

如果是这样，Laravel 将尝试加载一个 .env.[APP_ENV] 文件（如果存在）。

如果该文件不存在，则将加载默认的 .env 文件。

Environment Variable Types - 环境变量类型

All variables in your .env files are typically parsed as strings, so some reserved values have been created to allow you to return a wider range of types from the env() function:

通常，.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

If you need to define an environment variable with a value that contains spaces, you may do so by enclosing the value in double quotes:

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

APP_NAME="My Application"

Retrieving Environment Configuration - 获取环境配置

All of the variables listed in the .env file will be loaded into the $_ENV PHP super-global when your application receives a request.

当你的应用程序接收到请求时，.env 文件中列出的所有变量都将加载到 $_ENV PHP 超全局变量 中。

However, you may use the env function to retrieve values from these variables in your configuration files.

但是，你可以使用 env 函数、来从这些变量中检索值，这些变量在你的配置文件中。

In fact, if you review the Laravel configuration files, you will notice many of the options are already using this function:

事实上，如果你查看Laravel 配置文件，你会注意到许多选项已经在使用这个函数：

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

The second value passed to the env function is the “default value”.

This value will be returned if no environment variable exists for the given key.

传递给 env 函数的第二个值是"默认值"。

如果给定键没有对应的环境变量，则将返回此值。

Determining the Current Environment - 确定当前环境

The current application environment is determined via the APP_ENV variable from your .env file.

You may access this value via the environment method on the App facade:

当前应用程序环境是通过.env 文件中的 APP_ENV 变量确定的。

你可以通过 App facade 上的 environment 方法访问此值：

use Illuminate\Support\Facades\App;
 
$environment = App::environment();

You may also pass arguments to the environment method to determine if the environment matches a given value.

你也可以向 environment 方法传递参数，以确定环境是否匹配给定的值。

The method will return true if the environment matches any of the given values:

如果环境与给定的任何值匹配，该方法将返回true：

if (App::environment('local')) {
    // The environment is local
}
 
if (App::environment(['local', 'staging'])) {
    // The environment is either local OR staging...
}

The current application environment detection can be overridden by defining a server-level APP_ENV environment variable.

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

Encrypting Environment Files - 加密环境文件

Unencrypted environment files should never be stored in source control.

However, Laravel allows you to encrypt your environment files so that they may safely be added to source control with the rest of your application.

不应在源代码控制中存储未加密的环境文件。

但是，Laravel 允许你加密环境文件，以便它们可以安全地与应用程序的其余部分一起添加到源代码控制中。

Encryption - 加密

To encrypt an environment file, you may use the env:encrypt command:

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

php artisan env:encrypt

Running the env:encrypt command will encrypt your .env file and place the encrypted contents in an .env.encrypted file.

The decryption key is presented in the output of the command and should be stored in a secure password manager.

If you would like to provide your own encryption key you may use the --key option when invoking the command:

运行 env:encrypt 命令将加密你的 .env 文件，并将加密内容放入一个 .env.encrypted 文件中。

解密密钥将显示在命令的输出中，应存储在安全的密码管理器中。

如果想提供自己的加密密钥，可以在调用命令时使用 --key 选项：

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

The length of the key provided should match the key length required by the encryption cipher being used.

提供的密钥长度应与加密使用的加密器所需的密钥长度匹配。

By default, Laravel will use the AES-256-CBC cipher which requires a 32 character key.

默认情况下，Laravel 将使用 AES-256-CBC 加密器，需要一个 32 个字符的密钥。

You are free to use any cipher supported by Laravel’s encrypter by passing the --cipher option when invoking the command.

你可以通过在调用命令时传递 --cipher 选项，自由地使用 Laravel 的 加密器 支持的任何加密器。

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:

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

php artisan env:encrypt --env=staging

Decryption - 解密

To decrypt an environment file, you may use the env:decrypt command.

要解密一个环境文件，可以使用 env:decrypt 命令。

This command requires a decryption key, which Laravel will retrieve from the LARAVEL_ENV_ENCRYPTION_KEY environment variable:

这个命令需要一个解密密钥，Laravel 将从 LARAVEL_ENV_ENCRYPTION_KEY 环境变量中检索。

php artisan env:decrypt

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

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

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.

当调用 env:decrypt 命令时，Laravel 将解密 .env.encrypted 文件的内容并将解密后的内容放入 .env 文件中。

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

--cipher 选项可以在 env:decrypt 命令中提供，以使用自定义加密器：

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:

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

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:

为了覆盖现有的环境文件，可以在 env:decrypt 命令中提供 --force 选项：

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.

你可以在应用程序的任何地方使用 Config 门面或全局 config 函数轻松访问配置数值。

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 方法或将一个数组传递给 config 函数：

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.

为了辅助静态分析，Config 门面还提供了带有类型的配置检索方法。

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.

为了加速应用程序，你应该使用 config:cache Artisan 命令将所有配置文件缓存到一个单独的文件中。

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.

通常应该在生产部署过程中运行 php artisan config:cache 命令。

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.

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

For this reason, you should ensure you are only calling the env function from within your application’s configuration (config) files.

因此，应确保只从应用程序的配置 (config) 文件中调用 env 函数。

You can see many examples of this by examining Laravel’s default configuration files.

你可以通过查看 Laravel 的默认配置文件来查看许多示例。

Configuration values may be accessed from anywhere in your application using the config function described above.

可以使用上述描述的 config 函数从应用程序的任何地方访问配置数值。

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

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

php artisan config:clear

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.

如果在部署过程中执行 config:cache 命令，请确保只从配置文件中调用 env 函数。

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.

一旦配置被缓存，.env 文件将不会被加载；因此，env 函数将只返回外部系统级环境变量。

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.

大多数 Laravel 的配置文件已经发布在应用程序的 config 目录中；

但是，像 cors.php 和 view.php 这样的特定配置文件默认情况下未发布，因为大多数应用程序不需要对它们进行修改。

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

然而，你可以使用 config:publish Artisan 命令来发布任何默认未发布的配置文件：

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.

在您的 config/app.php 配置文件中的 debug 选项确定了错误信息对用户显示的程度。

By default, this option is set to respect the value of the APP_DEBUG environment variable, which is stored in your .env file.

默认情况下，该选项设置为遵循 .env 文件中存储的 APP_DEBUG 环境变量的值。

For local development, you should set the APP_DEBUG environment variable to true. **In your production environment, this value should always be false. **

对于本地开发，您应该将 APP_DEBUG 环境变量设置为 true。在生产环境中，这个值应该始终设置为 false。

If the variable is set to true in production, you risk exposing sensitive configuration values to your application’s end users.

如果在生产中将变量设置为 true，您会面临将敏感配置值暴露给应用最终用户的风险。

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.

如果应用程序处于维护模式，将抛出一个状态码为 503 的 Symfony\Component\HttpKernel\Exception\HttpException 实例。

To enable maintenance mode, execute the down Artisan command:

要启用维护模式，请执行 down Artisan 命令：

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.

如果希望在所有维护模式响应中发送 Refresh HTTP 头，可以在调用 down 命令时提供 refresh 选项。

The Refresh header will instruct the browser to automatically refresh the page after the specified number of seconds:

Refresh 头将指示浏览器在指定的秒数后自动刷新页面：

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:

您还可以为 down 命令提供一个 retry 选项，该选项将被设置为 Retry-After HTTP 标头的值，尽管浏览器通常会忽略此标头。

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:

要允许使用秘密令牌绕过维护模式，您可以使用 secret 选项来指定一个维护模式绕过令牌：

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:

在将应用程序置于维护模式后，您可以导航至与该令牌匹配的应用程序 URL，Laravel 将向您的浏览器发放维护模式绕过 cookie：

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:

如果您希望 Laravel 为您生成秘密令牌，您可以使用 with-secret 选项。

一旦应用程序处于维护模式，秘密令牌将显示给您：

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.

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 &.

当访问这个隐藏路由时，您将被重定向到应用程序的 / 路由。

一旦 cookie 发放给您的浏览器，您将可以正常地浏览应用程序，就像它没有处于维护模式一样。

您的维护模式秘密令牌通常应由字母和数字字符组成，也可以选择包含破折号。

请避免使用在 URL 中具有特殊含义的字符，如 ? 或 &。

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 “driver” setting in the config/app.php file of your application to cache.

Then, select a cache store that is accessible by all your servers.

This ensures the maintenance mode status is consistently maintained across every server:

默认情况下，Laravel 使用基于文件的系统来确定您的应用程序是否处于维护模式。

这意味着要激活维护模式，必须在托管应用程序的每个服务器上执行 php artisan down 命令。

此外，Laravel 还提供了基于缓存的方法来处理维护模式。

这种方法只需要在一个服务器上运行 php artisan down 命令。

要使用这种方法，修改您的应用程序的 config/app.php 文件中的 “driver” 设置为 cache。

然后，选择一个所有服务器都可以访问的缓存 store。

这样可以确保维护模式状态在每台服务器上保持一致。

'maintenance' => [
    'driver' => 'cache',
    '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 命令，那么当用户访问应用程序时，如果您的 Composer 依赖项或其他基础设施组件正在更新，他们仍然可能偶尔会遇到错误。

这是因为 Laravel 框架的一个重要部分必须启动，以便确定您的应用程序是否处于维护模式，并使用模板引擎呈现维护模式视图。

因此，Laravel 允许您预先呈现一个维护模式视图，在请求周期的一开始返回该视图。

这个视图是在您的应用程序的任何依赖项加载之前呈现的。

您可以使用 down 命令的 render 选项预先呈现您选择的模板：

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:

在维护模式下，Laravel 将为用户尝试访问的所有应用程序 URL 显示维护模式视图。

如果您希望，您可以指示 Laravel 将所有请求重定向到特定的 URL。

这可以通过使用 redirect 选项来实现。

例如，您可能希望将所有请求重定向到 / URI：

php artisan down --redirect=/

Disabling Maintenance Mode - 禁用维护模式

To disable maintenance mode, use the up command:

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

php artisan up

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

你可以通过在 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 alternatives like Laravel Vapor and Envoyer to accomplish zero-downtime deployment with Laravel.

由于维护模式需要你的应用程序有几秒钟的停机时间，考虑使用 Laravel Vapor 和 Envoyer 等替代方案，以实现 Laravel 的零停机部署。