配置

簡介
環境配置
存取配置值
配置快取
配置發布
除錯模式
維護模式

簡介

Laravel 框架的所有配置檔案都儲存在 config 目錄中。每個選項都有文檔說明，因此請隨意瀏覽檔案並熟悉可用的選項。

這些配置檔案允許您配置諸如資料庫連接資訊、郵件伺服器資訊以及各種其他核心配置值（如應用程式 URL 和加密金鑰）等內容。

`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。

Laravel 的預設 .env 檔案包含一些常見的配置值，這些值可能因應用程式是在本機運行還是在生產 Web 伺服器上運行而有所不同。然後，config 目錄中的配置檔案使用 Laravel 的 env 函數讀取這些值。

如果您與團隊一起開發，您可能希望繼續包含並更新應用程式的 .env.example 檔案。透過在範例配置檔案中放置佔位符值，團隊中的其他開發者可以清楚地看到執行您的應用程式需要哪些環境變數。

[!NOTE] .env 檔案中的任何變數都可以被外部環境變數（如伺服器級別或系統級別的環境變數）覆蓋。

環境檔案安全性

您的 .env 檔案不應提交到應用程式的原始碼控制中，因為使用您應用程式的每個開發者/伺服器可能需要不同的環境配置。此外，如果入侵者獲得對您的原始碼控制儲存庫的存取權限，這將是一個安全風險，因為任何敏感憑證都會被暴露。

然而，您可以使用 Laravel 內建的環境加密來加密您的環境檔案。加密的環境檔案可以安全地放入原始碼控制中。

其他環境檔案

在載入應用程式的環境變數之前，Laravel 會判斷是否已外部提供 APP_ENV 環境變數或是否已指定 --env CLI 參數。如果是，Laravel 將嘗試載入 .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 檔案中列出的所有變數都將被載入到 $_ENV PHP 超級全域變數中。但是，您可以在配置檔案中使用 env 函數從這些變數中檢索值。事實上，如果您查看 Laravel 配置檔案，您會注意到許多選項已經使用了此函數：

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

傳遞給 env 函數的第二個值是「預設值」。如果給定的金鑰不存在環境變數，將返回此值。

判斷當前環境

當前應用程式環境透過 .env 檔案中的 APP_ENV 變數確定。您可以透過 App Facade 的 environment 方法存取此值：

use Illuminate\Support\Facades\App;

$environment = App::environment();

您也可以向 environment 方法傳遞參數來判斷環境是否與給定值匹配。如果環境與任何給定值匹配，該方法將返回 true：

if (App::environment('local')) {
    // 環境是 local
}

if (App::environment(['local', 'staging'])) {
    // 環境是 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 個字元的金鑰。您可以透過在調用命令時傳遞 --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...

使用可讀格式允許您查看存在哪些環境變數，而不暴露敏感資料。它還使審查拉取請求變得更加容易，因為您可以查看添加、刪除或重新命名了哪些變數，而無需解密檔案。

解密環境檔案時，Laravel 會自動偵測使用了哪種格式，因此 env:decrypt 命令不需要額外的選項。

[!NOTE] 使用 --readable 選項時，原始環境檔案中的註解和空行不會包含在加密輸出中。

解密

要解密環境檔案，您可以使用 env:decrypt 命令。此命令需要一個解密金鑰，Laravel 將從 LARAVEL_ENV_ENCRYPTION_KEY 環境變數中檢索：

php artisan env:decrypt

或者，可以透過 --key 選項直接將金鑰提供給命令：

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

當調用 env:decrypt 命令時，Laravel 將解密 .env.encrypted 檔案的內容，並將解密後的內容放入 .env 檔案中。

可以向 env:decrypt 命令提供 --cipher 選項以使用自訂加密密碼：

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

如果您的應用程式有多個環境檔案，如 .env 和 .env.staging，您可以透過 --env 選項提供環境名稱來指定應解密的環境檔案：

php artisan env:decrypt --env=staging

要覆蓋現有的環境檔案，您可以向 env:decrypt 命令提供 --force 選項：

php artisan env:decrypt --force

存取配置值

您可以使用 Config Facade 或全域 config 函數從應用程式中的任何位置輕鬆存取配置值。可以使用「點」語法存取配置值，該語法包括您要存取的檔案名稱和選項。也可以指定預設值，如果配置選項不存在，將返回該預設值：

use Illuminate\Support\Facades\Config;

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

$value = config('app.timezone');

// 如果配置值不存在，則檢索預設值...
$value = config('app.timezone', 'Asia/Seoul');

要在運行時設定配置值，您可以調用 Config Facade 的 set 方法或向 config 函數傳遞一個陣列：

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

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

為了輔助靜態分析，Config Facade 還提供了類型化的配置檢索方法。如果檢索到的配置值與預期類型不匹配，將拋出異常：

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

配置快取

為了給您的應用程式加速，您應該使用 config:cache Artisan 命令將所有配置檔案快取到單個檔案中。這將把應用程式的所有配置選項合併到一個檔案中，框架可以快速載入。

您通常應該將 php artisan config:cache 命令作為生產部署過程的一部分來執行。在本機開發期間不應運行該命令，因為在應用程式開發過程中可能需要頻繁更改配置選項。

配置被快取後，框架在請求或 Artisan 命令期間不會載入應用程式的 .env 檔案；因此，env 函數只會返回外部的系統級環境變數。

出於這個原因，您應該確保只從應用程式的配置（config）檔案中調用 env 函數。您可以透過檢查 Laravel 的預設配置檔案來看到許多範例。可以使用上面描述的 config 函數從應用程式中的任何位置存取配置值。

config:clear 命令可用於清除快取的配置：

php artisan config:clear

[!WARNING] 如果您在部署過程中執行 config:cache 命令，您應該確保只從配置檔案中調用 env 函數。一旦配置被快取，.env 檔案將不會被載入；因此，env 函數只會返回外部的系統級環境變數。

配置發布

Laravel 的大多數配置檔案已經發佈在應用程式的 config 目錄中；然而，某些配置檔案（如 cors.php 和 view.php）預設不會發佈，因為大多數應用程式永遠不需要修改它們。

但是，您可以使用 config:publish Artisan 命令來發佈任何預設未發佈的配置檔案：

php artisan config:publish

php artisan config:publish --all

除錯模式

config/app.php 配置檔案中的 debug 選項決定實際向使用者顯示多少錯誤資訊。預設情況下，此選項設定為尊重 .env 檔案中儲存的 APP_DEBUG 環境變數的值。

[!WARNING] 對於本機開發，您應該將 APP_DEBUG 環境變數設定為 true。在生產環境中，此值應始終為 false。如果在生產中將變數設定為 true，您將面臨向應用程式的最終使用者暴露敏感配置值的風險。

維護模式

當您的應用程式處於維護模式時，所有進入應用程式的請求都將顯示自訂視圖。這使得在應用程式更新或執行維護時輕鬆「禁用」應用程式。維護模式檢查包含在應用程式的預設中介層堆疊中。如果應用程式處於維護模式，將拋出狀態代碼為 503 的 Symfony\Component\HttpKernel\Exception\HttpException 實例。

要啟用維護模式，請執行 down Artisan 命令：

php artisan down

如果您希望所有維護模式響應都發送 Refresh HTTP 標頭，可以在調用 down 命令時提供 refresh 選項。Refresh 標頭將指示瀏覽器在指定的秒數後自動刷新頁面：

php artisan down --refresh=15

您也可以向 down 命令提供 retry 選項，該選項將被設置為 Retry-After HTTP 標頭的值，儘管瀏覽器通常會忽略此標頭：

php artisan down --retry=60

繞過維護模式

要允許使用秘密令牌繞過維護模式，您可以使用 secret 選項指定維護模式繞過令牌：

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

將應用程式置於維護模式後，您可以導航到與此令牌匹配的應用程式 URL，Laravel 將向您的瀏覽器發送一個維護模式繞過 Cookie：

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

如果您希望 Laravel 為您生成秘密令牌，可以使用 with-secret 選項。一旦應用程式進入維護模式，秘密將顯示給您：

php artisan down --with-secret

存取此隱藏路由時，您將被重定向到應用程式的 / 路由。一旦 Cookie 被發送到您的瀏覽器，您將能夠正常瀏覽應用程式，就像它不在維護模式一樣。

[!NOTE] 您的維護模式秘密通常應由字母數字字元組成，並可選擇包含破折號。您應避免使用在 URL 中具有特殊含義的字元，如 ? 或 &。

多伺服器上的維護模式

預設情況下，Laravel 使用基於檔案的系統來判斷您的應用程式是否處於維護模式。這意味著要啟用維護模式，必須在託管您應用程式的每台伺服器上執行 php artisan down 命令。

或者，Laravel 提供了一種基於快取的方法來處理維護模式。此方法只需要在一台伺服器上運行 php artisan down 命令。要使用此方法，請修改應用程式 .env 檔案中的維護模式變數。您應該選擇所有伺服器都可存取的快取 store。這確保維護模式狀態在每台伺服器上保持一致：

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

預渲染維護模式視圖

如果您在部署期間使用 php artisan down 命令，如果使用者在您的 Composer 依賴項或其他基礎架構元件更新時存取應用程式，他們仍可能偶爾遇到錯誤。這是因為 Laravel 框架的很大一部分必須引導以判斷您的應用程式是否處於維護模式，並使用模板引擎渲染維護模式視圖。

出於這個原因，Laravel 允許您預渲染一個維護模式視圖，該視圖將在請求週期的最開始返回。此視圖在您的應用程式的任何依賴項載入之前渲染。您可以使用 down 命令的 render 選項預渲染您選擇的模板：

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

重定向維護模式請求

處於維護模式時，Laravel 將為使用者嘗試存取的所有應用程式 URL 顯示維護模式視圖。如果您願意，可以指示 Laravel 將所有請求重定向到特定 URL。這可以使用 redirect 選項來實現。例如，您可能希望將所有請求重定向到 / URI：

php artisan down --redirect=/

禁用維護模式

要禁用維護模式，請使用 up 命令：

php artisan up

[!NOTE] 您可以透過在 resources/views/errors/503.blade.php 中定義自己的模板來自訂預設維護模式模板。

維護模式和佇列

當您的應用程式處於維護模式時，不會處理任何佇列任務。一旦應用程式退出維護模式，任務將恢復正常處理。

維護模式的替代方案

由於維護模式需要您的應用程式有數秒的停機時間，請考慮在像 Laravel Cloud 這樣的全託管平台上運行您的應用程式，以實現使用 Laravel 的零停機時間部署。

配置

配置

簡介

about 命令