> ## 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` 檔案內的變數會在請求進來時載入到 `$_ENV` PHP 超全域變數。在設定檔中可透過 `env()` 函式取得值。

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

第 2 個參數為預設值，當該環境變數不存在時會回傳它。

### 取得目前的環境

目前的環境是由 `.env` 檔案的 `APP_ENV` 決定。可透過 `App` Facade 的 `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` Facade 或全域 `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
```

### 略過維護模式

若想以秘密 token 允許特定使用者存取，可用 `--secret` 選項。

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

使用 `--with-secret` 選項時，Laravel 會自動產生 token。

```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-TW/routing">
  學習連結 URL 與控制器的路由基礎。
</Card>


## Related topics

- [資料庫設定](/zh-TW/database.md)
- [雜湊（Hashing）](/zh-TW/hashing.md)
- [WebSocket (Jetstream / Firehose)](/zh-TW/packages/laravel-bluesky/websocket.md)
- [密碼重設](/zh-TW/passwords.md)
- [圖片加工](/zh-TW/images.md)