> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 配置

> 介绍 Laravel 的配置文件、环境变量（.env）、配置值的读取方式、缓存、调试模式以及维护模式。

## 简介

Laravel 框架的所有配置文件都存放在 `config/` 目录下。每个选项都带有注释，可以打开文件查看可用的选项。

配置文件用来管理数据库连接信息、邮件服务器信息、应用 URL 与加密密钥等各种核心设置。

```mermaid theme={null}
flowchart LR
    A[".env 文件"] -->|env()| B["config/ 文件"]
    B -->|config()| C["应用"]
```

### `about` 命令

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

```shell theme={null}
php artisan about
```

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

```shell theme={null}
php artisan about --only=environment
```

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

```shell theme={null}
php artisan config:show database
```

## 环境配置（.env）

在实际开发中，我们经常希望根据运行环境切换配置值。比如本地和生产环境使用不同的缓存驱动。

Laravel 借助 [DotEnv](https://github.com/vlucas/phpdotenv) PHP 库来简化这件事。全新安装时，应用根目录会包含一个 `.env.example` 文件（其中定义了常见的环境变量），安装过程会自动将其复制为 `.env`。

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

### 环境文件的安全性

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

不过，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`  |

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

```ini theme={null}
APP_NAME="My Application"
```

### 读取环境变量

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

```php theme={null}
'debug' => (bool) env('APP_DEBUG', false),
```

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

### 判断当前环境

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

```php theme={null}
use Illuminate\Support\Facades\App;

$environment = App::environment();
```

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

```php theme={null}
if (App::environment('local')) {
    // 本地环境
}

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

### 加密环境文件

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

```shell theme={null}
php artisan env:encrypt
```

执行后 `.env` 会被加密，密文保存到 `.env.encrypted` 中。解密密钥会在命令输出中展示，请存放到安全的密码管理器中。

解密使用 `env:decrypt` 命令。

```shell theme={null}
php artisan env:decrypt
```

## 访问配置值

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

```php theme={null}
use Illuminate\Support\Facades\Config;

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

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

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

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

```php theme={null}
Config::set('app.timezone', 'America/Chicago');

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

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

```php theme={null}
Config::string('config-key');
Config::integer('config-key');
Config::float('config-key');
Config::boolean('config-key');
Config::array('config-key');
Config::collection('config-key');
```

## 缓存配置

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

```shell theme={null}
php artisan config:cache
```

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

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

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

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

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

```shell theme={null}
php artisan config:clear
```

### 发布配置文件

Laravel 大多数配置文件都已经放在 `config/` 目录中，但 `cors.php`、`view.php` 等文件默认并未发布。

要发布尚未发布的配置文件，使用 `config:publish` 命令。

```shell theme={null}
php artisan config:publish

php artisan config:publish --all
```

## 调试模式

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

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

```ini theme={null}
# 本地开发
APP_DEBUG=true

# 生产环境
APP_DEBUG=false
```

## 维护模式

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

### 启用维护模式

```shell theme={null}
php artisan down
```

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

```shell theme={null}
php artisan down --refresh=15
```

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

```shell theme={null}
php artisan down --retry=60
```

### 绕过维护模式

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

```shell theme={null}
php artisan down --secret="1630542a-246b-4b66-afa1-dd72a4c43515"
```

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

```shell theme={null}
php artisan down --with-secret
```

### 多服务器下的维护模式

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

```ini theme={null}
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database
```

### 预渲染维护视图

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

```shell theme={null}
php artisan down --render="errors::503"
```

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

```shell theme={null}
php artisan down --redirect=/
```

### 关闭维护模式

```shell theme={null}
php artisan up
```

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

<Tip>
  如果希望完全消除停机时间，可以考虑 [Laravel Cloud](https://cloud.laravel.com) 这类全托管平台。
</Tip>

## 下一步

<Card title="路由" icon="route" href="/zh/routing">
  学习将 URL 与控制器绑定的路由基础。
</Card>


## Related topics

- [WebSocket (Jetstream / Firehose)](/zh/packages/laravel-bluesky/websocket.md)
- [哈希（Hashing）](/zh/hashing.md)
- [Labeler](/zh/packages/laravel-bluesky/labeler.md)
- [日志](/zh/logging.md)
- [密码重置](/zh/passwords.md)