設定

• 簡介
• 環境設定
  • 環境變數類型
  • 擷取環境設定
  • 判斷目前環境
  • 加密環境檔案
• 存取設定值
• 設定快取
• 設定發佈
• 偵錯模式
• 維護模式

簡介

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

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

about 命令

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

1php artisan about

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

1php artisan about --only=environment

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

1php artisan config:show database

環境設定

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

為了簡化此操作，Laravel 使用了 DotEnv PHP 函式庫。在全新的 Laravel 安裝中，應用程式的根目錄將包含一個 .env.example 檔案，其中定義了許多常見的環境變數。在 Laravel 安裝過程中，此檔案將自動複製到 .env。

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

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

環境檔案安全性

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

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

其他環境檔案

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

環境變數類型

您的 .env 檔案中的所有變數通常都解析為字串，因此建立了一些保留值，讓您可以從 env() 函數傳回更廣泛的類型

如果您需要定義一個值包含空格的環境變數，您可以將該值用雙引號括起來

1APP_NAME="My Application"

擷取環境設定

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

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

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

判斷目前環境

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

1use Illuminate\Support\Facades\App;
2 
3$environment = App::environment();

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

1if (App::environment('local')) {
2    // The environment is local
3}
4 
5if (App::environment(['local', 'staging'])) {
6    // The environment is either local OR staging...
7}

加密環境檔案

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

加密

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

1php artisan env:encrypt

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

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

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

1php artisan env:encrypt --env=staging

解密

若要解密環境檔案，您可以使用 env:decrypt 命令。此命令需要解密金鑰，Laravel 將從 LARAVEL_ENV_ENCRYPTION_KEY 環境變數中擷取該金鑰

1php artisan env:decrypt

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

1php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

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

可以將 --cipher 選項提供給 env:decrypt 命令，以便使用自訂加密密碼演算法

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

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

1php artisan env:decrypt --env=staging

若要覆寫現有的環境檔案，您可以將 --force 選項提供給 env:decrypt 命令

1php artisan env:decrypt --force

存取設定值

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

1use Illuminate\Support\Facades\Config;
2 
3$value = Config::get('app.timezone');
4 
5$value = config('app.timezone');
6 
7// Retrieve a default value if the configuration value does not exist...
8$value = config('app.timezone', 'Asia/Seoul');

若要在執行階段設定設定值，您可以叫用 Config facade 的 set 方法，或將陣列傳遞給 config 函數

1Config::set('app.timezone', 'America/Chicago');
2 
3config(['app.timezone' => 'America/Chicago']);

為了協助靜態分析，Config facade 也提供類型化的設定擷取方法。如果擷取的設定值與預期的類型不符，則會擲回例外

1Config::string('config-key');
2Config::integer('config-key');
3Config::float('config-key');
4Config::boolean('config-key');
5Config::array('config-key');

設定快取

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

您通常應該在生產部署過程中執行 php artisan config:cache 命令。該命令不應在本機開發期間執行，因為在應用程式開發過程中，設定選項將經常需要變更。

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

因此，您應確保僅從應用程式的設定 (config) 檔案中呼叫 env 函數。您可以透過檢查 Laravel 的預設設定檔來查看許多範例。可以使用 如上所述的 config 函數從應用程式中的任何位置存取設定值。

config:clear 命令可用於清除快取的設定

1php artisan config:clear

設定發佈

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

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

1php artisan config:publish
2 
3php artisan config:publish --all

偵錯模式

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

維護模式

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

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

1php artisan down

如果您希望 Refresh HTTP 標頭與所有維護模式回應一起傳送，您可以在叫用 down 命令時提供 refresh 選項。Refresh 標頭將指示瀏覽器在指定的秒數後自動重新整理頁面

1php artisan down --refresh=15

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

1php artisan down --retry=60

繞過維護模式

若要允許使用密碼權杖繞過維護模式，您可以使用 secret 選項來指定維護模式繞過權杖

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

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

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

如果您希望 Laravel 為您產生密碼權杖，您可以使用 with-secret 選項。密碼將在應用程式處於維護模式後顯示給您

1php artisan down --with-secret

存取此隱藏路由時，您將被重新導向到應用程式的 / 路由。一旦 Cookie 已發行到您的瀏覽器，您就可以像應用程式未處於維護模式一樣正常瀏覽應用程式。

多伺服器上的維護模式

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

或者，Laravel 提供了一種基於快取的方法來處理維護模式。此方法只需要在一個伺服器上執行 php artisan down 命令。若要使用此方法，請將應用程式的 config/app.php 檔案中的「driver」設定修改為 cache。然後，選取所有伺服器都可存取的快取 store。這可確保在每部伺服器上一致地維護維護模式狀態

1'maintenance' => [
2    'driver' => 'cache',
3    'store' => 'database',
4],

預先呈現維護模式視圖

如果您在部署期間使用 php artisan down 命令，則當使用者在更新 Composer 相依性或其他基礎架構元件時存取應用程式時，使用者可能仍會偶爾遇到錯誤。發生這種情況的原因是，為了判斷您的應用程式是否處於維護模式並使用範本引擎呈現維護模式視圖，Laravel 框架的很大一部分必須啟動。

因此，Laravel 允許您預先呈現維護模式視圖，該視圖將在請求週期的最開始傳回。此視圖是在載入應用程式的任何相依性之前呈現的。您可以使用 down 命令的 render 選項預先呈現您選擇的範本

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

重新導向維護模式請求

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

1php artisan down --redirect=/

停用維護模式

若要停用維護模式，請使用 up 命令

1php artisan up

維護模式和佇列

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

維護模式的替代方案

由於維護模式需要您的應用程式停機數秒，因此請考慮在完全託管的平台 (例如 Laravel Cloud) 上執行您的應用程式，以使用 Laravel 完成零停機時間部署。