LaravelDocs（中文）

設定 (Configuration)

簡介 (Introduction)

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

這些設定檔允許您設定資料庫連線資訊、郵件伺服器資訊，以及各種其他核心設定值，例如您的應用程式 URL 和加密金鑰。

about 指令 (The About Command)

Laravel 可以透過 about Artisan 指令顯示應用程式的設定、驅動程式和環境的概覽。

php artisan about

如果您只對應用程式概覽輸出的特定部分感興趣，可以使用 --only 選項來篩選該部分：

php artisan about --only=environment

或者，要詳細探索特定設定檔的值，您可以使用 config:show Artisan 指令：

php artisan config:show database

環境設定 (Environment Configuration)

根據應用程式執行的環境擁有不同的設定值通常很有幫助。例如，您可能希望在本機使用與正式環境伺服器不同的快取驅動程式。

為了讓這變得輕而易舉，Laravel 利用了 DotEnv PHP 函式庫。在全新的 Laravel 安裝中，應用程式的根目錄將包含一個 .env.example 檔案，其中定義了許多常見的環境變數。在 Laravel 安裝過程中，此檔案會自動複製到 .env。

Laravel 的預設 .env 檔案包含一些常見的設定值，這些值可能會根據您的應用程式是在本機執行還是在正式環境 Web 伺服器上執行而有所不同。然後，config 目錄中的設定檔會使用 Laravel 的 env 函式讀取這些值。

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

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

環境檔案安全性 (Environment File Security)

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

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

額外的環境檔案 (Additional Environment Files)

在載入應用程式的環境變數之前，Laravel 會判斷是否已從外部提供 APP_ENV 環境變數，或者是否已指定 --env CLI 參數。如果是，Laravel 將嘗試載入 .env.[APP_ENV] 檔案（如果存在）。如果不存在，則會載入預設的 .env 檔案。

環境變數類型 (Environment Variable Types)

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

取得環境設定 (Retrieving Environment Configuration)

當您的應用程式收到請求時，.env 檔案中列出的所有變數都將載入到 $_ENV PHP 超全域變數中。但是，您可以使用 env 函式從設定檔中檢索這些變數的值。事實上，如果您查看 Laravel 設定檔，您會注意到許多選項已經在使用此函式：

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

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

判斷目前環境 (Determining The Current Environment)

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

use Illuminate\Support\Facades\App;

$environment = App::environment();

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

if (App::environment('local')) {
    // The environment is local
}

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

[!NOTE] 目前的應用程式環境偵測可以透過定義伺服器級 APP_ENV 環境變數來覆蓋。

加密環境檔案 (Encrypting Environment Files)

未加密的環境檔案永遠不應儲存在原始碼控制中。但是，Laravel 允許您加密環境檔案，以便可以將它們與應用程式的其餘部分一起安全地新增到原始碼控制中。

加密 (Encryption)

要加密環境檔案，您可以使用 env:encrypt 指令：

php artisan env:encrypt

執行 env:encrypt 指令將加密您的 .env 檔案並將加密內容放置在 .env.encrypted 檔案中。解密金鑰顯示在指令的輸出中，應儲存在安全的密碼管理器中。如果您想提供自己的加密金鑰，可以在呼叫指令時使用 --key 選項：

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

[!NOTE] 提供的金鑰長度應符合所使用的加密 cipher 所需的金鑰長度。預設情況下，Laravel 將使用 AES-256-CBC cipher，這需要 32 個字元的金鑰。您可以自由使用 Laravel 加密器 支援的任何 cipher，只需在呼叫指令時傳遞 --cipher 選項即可。

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

php artisan env:encrypt --env=staging

解密 (Decryption)

要解密環境檔案，您可以使用 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 選項以使用自訂加密 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

存取設定值 (Accessing Configuration Values)

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

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');

要在執行時設定設定值，您可以呼叫 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');

設定快取 (Configuration Caching)

為了提升應用程式的速度，您應該使用 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 函式將只返回外部的、系統級的環境變數。

發布設定 (Configuration Publishing)

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

但是，您可以使用 config:publish Artisan 指令發布任何預設未發布的設定檔：

php artisan config:publish

php artisan config:publish --all

除錯模式 (Debug Mode)

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

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

維護模式 (Maintenance Mode)

當您的應用程式處於維護模式時，將為進入應用程式的所有請求顯示一個自訂視圖。這使得在更新或執行維護時「停用」您的應用程式變得容易。維護模式檢查包含在應用程式的預設 Middleware 堆疊中。如果應用程式處於維護模式，將拋出一個狀態碼為 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

繞過維護模式 (Bypassing Maintenance Mode)

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

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

將應用程式置於維護模式後，您可以導航到符合此 Token 的應用程式 URL，Laravel 將向您的瀏覽器發出維護模式繞過 Cookie：

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

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

php artisan down --with-secret

存取此隱藏路由時，您將被重新導向到應用程式的 / 路由。一旦 Cookie 發出到您的瀏覽器，您將能夠正常瀏覽應用程式，就好像它沒有處於維護模式一樣。

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

多台伺服器上的維護模式 (Maintenance Mode On Multiple Servers)

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

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

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

預先渲染維護模式視圖 (Pre Rendering The Maintenance Mode View)

如果您在部署期間使用 php artisan down 指令，如果您的使用者在 Composer 依賴項目或其他基礎設施組件更新時存取應用程式，他們有時仍可能會遇到錯誤。這是因為 Laravel 框架的很大一部分必須啟動才能判斷您的應用程式處於維護模式並使用樣板引擎渲染維護模式視圖。

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

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

重新導向維護模式請求 (Redirecting Maintenance Mode Requests)

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

php artisan down --redirect=/

停用維護模式 (Disabling Maintenance Mode)

要停用維護模式，請使用 up 指令：

php artisan up

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

維護模式與 Queues (Maintenance Mode Queues)

當您的應用程式處於維護模式時，將不會處理任何 Queued jobs。一旦應用程式退出維護模式，Jobs 將繼續正常處理。

維護模式的替代方案 (Alternatives To Maintenance Mode)

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