配置 - Knowledge of Laravel

简介

Laravel 框架的所有配置文件都存放在 config/ 目录下。每个选项都带有注释，可以打开文件查看可用的选项。配置文件用来管理数据库连接信息、邮件服务器信息、应用 URL 与加密密钥等各种核心设置。

`about` 命令

使用 about Artisan 命令可以查看应用的配置、驱动与环境的概要。

php artisan about

若只想查看特定部分，可使用 --only 选项。

php artisan about --only=environment

若要详细查看某个配置文件的内容，可以使用 config:show 命令。

php artisan config:show database

环境配置（.env）

在实际开发中，我们经常希望根据运行环境切换配置值。比如本地和生产环境使用不同的缓存驱动。 Laravel 借助 DotEnv PHP 库来简化这件事。全新安装时，应用根目录会包含一个 .env.example 文件（其中定义了常见的环境变量），安装过程会自动将其复制为 .env。

团队协作时，建议随代码维护 .env.example 并放在仓库中。写好占位值，可以让团队其他成员清楚地知道需要哪些环境变量。

环境文件的安全性

请不要把 .env 文件提交到版本控制。每位开发者与每台服务器所需的配置不同，且一旦泄露仓库将带来安全事故风险。

不过，Laravel 内置了加密环境文件的功能，加密后就可以安全地保存到版本控制中。

额外的环境文件

在应用启动时，Laravel 会检查是否指定了 APP_ENV 环境变量或 CLI 的 --env 参数。若已指定且存在 .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`

要设置包含空格的值，请使用双引号。

APP_NAME="My Application"

读取环境变量

.env 中的所有变量在收到请求时会被加载到 PHP 超全局变量 $_ENV 中。在配置文件中可以通过 env() 函数获取。

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

第二个参数是默认值，当环境变量不存在时返回。

判断当前环境

当前环境由 .env 中的 APP_ENV 变量决定，可以通过 App 门面的 environment 方法获取。

use Illuminate\Support\Facades\App;

$environment = App::environment();

也可以传入参数来判断是否处于某个环境。

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

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

加密环境文件

未加密的环境文件不应保存到版本控制中，但 Laravel 提供了加密环境文件的功能。

加密

要加密环境文件，请使用 env:encrypt 命令。

php artisan env:encrypt

执行后 .env 会被加密，密文保存到 .env.encrypted 中。解密密钥会在命令输出中展示，请存放到安全的密码管理器中。若想指定自定义的加密密钥，可使用 --key 选项。

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

所提供的密钥长度必须与所用加密算法要求的密钥长度一致。默认情况下 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 命令无需额外的选项。

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

更新可读的加密文件

在更新可读格式的加密环境文件时，Laravel 会保留未变化的值，并移除已从原始环境文件中删除的变量。

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

若加密文件不存在，会自动创建。更新已有文件时，请使用与创建时相同的加密密钥与加密算法。若解密失败，命令不会覆盖已有文件而是直接失败。若想强制重新加密所有值，可以使用 --force 选项。可用于更换加密密钥或替换已失效的加密文件。

php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

解密

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

php artisan env:decrypt

也可以通过 --key 选项直接传入密钥。

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

执行 env:decrypt 命令后，Laravel 会解密 .env.encrypted 的内容并写入 .env 文件。若使用自定义加密算法，请指定 --cipher 选项。

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

若应用中有多个环境文件（例如 .env 与 .env.staging），可以通过 --env 选项指定要解密的环境。

php artisan env:decrypt --env=staging

若要覆盖已有的环境文件，请使用 --force 选项。

php artisan env:decrypt --force

访问配置值

可以通过 Config 门面或全局的 config() 函数在应用的任意位置访问配置值。使用「点号记法」，将文件名与选项名组合起来。

use Illuminate\Support\Facades\Config;

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

// 也可以用全局函数获取
$value = config('app.timezone');

// 指定不存在时的默认值
$value = config('app.timezone', 'Asia/Tokyo');

要在运行时更改配置值，可以使用 Config::set()，或者向 config() 传入数组。

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

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

也提供了带类型的取值方法，若类型不匹配会抛出异常。

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

缓存配置

要提升应用性能，可以将所有配置文件缓存到单个文件中。

php artisan config:cache

该命令会将所有配置选项汇总到一个文件里，使框架能更快地读取。

config:cache 命令应作为生产环境部署流程的一部分执行。本地开发过程中配置经常变动，不建议使用。

一旦生成了缓存，.env 文件在框架请求或运行 Artisan 命令时就不会再被加载。因此 env() 只会返回系统级环境变量。

正因如此，请务必只在 config/ 目录下的配置文件中使用 env()。应用其他地方获取配置请使用 config()。

要清除缓存，请使用 config:clear。

php artisan config:clear

发布配置文件

Laravel 大多数配置文件都已经放在 config/ 目录中，但 cors.php、view.php 等文件默认并未发布。要发布尚未发布的配置文件，使用 config:publish 命令。

php artisan config:publish

php artisan config:publish --all

调试模式

config/app.php 中的 debug 选项决定错误信息要展示给用户多少。该选项默认跟随 .env 中的 APP_DEBUG 环境变量。

生产环境请务必将 APP_DEBUG 设置为 false。 若保持 true，可能会将应用敏感配置暴露给终端用户。

# 本地开发
APP_DEBUG=true

# 生产环境
APP_DEBUG=false

维护模式

当应用处于维护模式时，所有请求都会显示自定义视图。这样在升级或维护期间可以临时「关闭」应用。

启用维护模式

php artisan down

指定 --refresh 选项可以让浏览器在指定秒数后自动刷新。

php artisan down --refresh=15

--retry 选项会设置为 Retry-After HTTP 头的值。

php artisan down --retry=60

绕过维护模式

若希望通过秘密令牌允许特定用户访问，使用 --secret 选项。

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

使用 --with-secret 选项则由 Laravel 自动生成令牌。

php artisan down --with-secret

多服务器下的维护模式

默认情况下 Laravel 以文件方式管理维护模式。多服务器场景下，建议改用基于缓存的方式。

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

预渲染维护视图

若在部署过程中执行 php artisan down，可能会有用户在依赖更新过程中看到错误。可以使用 --render 选项预先渲染视图，避免这种情况。

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

也可以将维护期间的所有请求重定向到指定 URL。

php artisan down --redirect=/

关闭维护模式

php artisan up

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

如果希望完全消除停机时间，可以考虑 Laravel Cloud 这类全托管平台。

下一步

路由

学习将 URL 与控制器绑定的路由基础。

入门

基础

请求处理

数据库

认证

辅助函数与外部通信

测试与部署

AI 开发辅助

配置

简介

`about` 命令

环境配置（.env）

环境文件的安全性

额外的环境文件

环境变量的类型

读取环境变量

判断当前环境

加密环境文件

加密

可读变量名

更新可读的加密文件

解密

访问配置值

缓存配置

发布配置文件

调试模式

维护模式

启用维护模式

绕过维护模式

多服务器下的维护模式

预渲染维护视图

关闭维护模式

下一步

路由

​简介

​about 命令

​环境配置（.env）

​环境文件的安全性

​额外的环境文件

​环境变量的类型

​读取环境变量

​判断当前环境

​加密环境文件

​加密

​可读变量名

​更新可读的加密文件

​解密

​访问配置值

​缓存配置

​发布配置文件

​调试模式

​维护模式

​启用维护模式

​绕过维护模式

​多服务器下的维护模式

​预渲染维护视图

​关闭维护模式

​下一步

路由

简介

`about` 命令

环境配置（.env）

环境文件的安全性

额外的环境文件

环境变量的类型

读取环境变量

判断当前环境

加密环境文件

加密

可读变量名

更新可读的加密文件

解密

访问配置值

缓存配置

发布配置文件

调试模式

维护模式

启用维护模式

绕过维护模式

多服务器下的维护模式

预渲染维护视图

关闭维护模式

下一步