Laradoc

Appearance

設定 ​

簡介 ​

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

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

about 命令 ​

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

shell
php artisan about

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

shell
php artisan about --only=environment

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

shell
php artisan config:show database

環境設定 ​

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

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

Laravel 預設的 .env 檔案包含了一些常見的設定值，這些設定值會因您的應用程式是運行在本地或正式網頁伺服器而有所不同。這些值會被 config 目錄中的設定檔使用 Laravel 的 env 函式讀取。

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

📌 備註

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

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

ini
APP_NAME="My Application"

取得環境設定 ​

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

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

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

判斷目前環境 ​

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

php
use Illuminate\Support\Facades\App;

$environment = App::environment();

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

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

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

📌 備註

可以透過定義伺服器層級的 APP_ENV 環境變數來覆寫目前的應用程式環境偵測。

加密環境檔案 ​

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

加密 ​

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

shell
php artisan env:encrypt

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

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

📌 備註

提供的金鑰長度應與所使用的加密密碼所需的金鑰長度匹配。預設情況下，Laravel 將使用 AES-256-CBC 密碼，該密碼需要 32 個字元的金鑰。您可以透過在調用命令時傳遞 --cipher 選項來使用 Laravel 的 加密器 支援的任何密碼。

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

shell
php artisan env:encrypt --env=staging

解密 ​

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

shell
php artisan env:decrypt

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

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

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

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

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

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

shell
php artisan env:decrypt --env=staging

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

shell
php artisan env:decrypt --force

存取設定值 ​

您可以在應用程式中的任何地方，輕鬆地使用 Config facade 或全域 config 函數來存取設定值。設定值可以使用「點」語法來存取，其中包括您希望存取的檔案名稱和選項。您也可以指定一個預設值，如果設定選項不存在，該預設值將會被回傳：

php
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 函數：

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

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

為了協助靜態分析，Config facade 也提供了型別化的設定值擷取方法。如果擷取的設定值與預期的型別不符，將會拋出例外：

php
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 命令可用於清除快取的設定：

shell
php artisan config:clear

⚠️ 警告

如果您在部署過程中執行 config:cache 命令，您應該確保只在設定檔中呼叫 env 函數。一旦設定被快取，.env 檔案將不會被載入；因此，env 函數只會回傳外部的系統層級環境變數。

發佈設定 ​

大部分的 Laravel 設定檔已發佈在應用程式的 config 目錄中；然而，某些設定檔（例如 cors.php 和 view.php）預設不會發佈，因為大多數應用程式無需修改它們。

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

shell
php artisan config:publish

php artisan config:publish --all

除錯模式 ​

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

⚠️ 警告

為了本地開發，您應該將 APP_DEBUG 環境變數設定為 true。在您的生產環境中，此值應始終為 false。 如果在生產環境中將變數設定為 true，您可能會將敏感的設定值暴露給應用程式的終端使用者。

維護模式 ​

當應用程式處於維護模式時，所有對應用程式的請求都將顯示自訂檢視。這使得在更新或執行維護時「停用」應用程式變得容易。應用程式的預設中介層 (middleware) 堆疊中包含了維護模式檢查。如果應用程式處於維護模式，則會丟出一個狀態碼為 503 的 Symfony\Component\HttpKernel\Exception\HttpException 實例。

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

shell
php artisan down

若要讓所有維護模式的回應都帶有 Refresh HTTP 標頭，您可以在執行 down 命令時提供 refresh 選項。Refresh 標頭會指示瀏覽器在指定秒數後自動重新整理頁面：

shell
php artisan down --refresh=15

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

shell
php artisan down --retry=60

繞過維護模式 ​

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

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

將應用程式設定為維護模式後，您可以導航至與此權杖匹配的應用程式 URL，Laravel 將會向您的瀏覽器發出一個維護模式繞過 Cookie：

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

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

shell
php artisan down --with-secret

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

📌 備註

您的維護模式密碼通常應由英數字元組成，並可選擇包含連字號。您應該避免使用在 URL 中具有特殊意義的字元，例如 ? 或 &。

多伺服器上的維護模式 ​

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

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

ini
APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

預先渲染維護模式檢視 ​

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

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

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

重新導向維護模式請求 ​

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

shell
php artisan down --redirect=/

停用維護模式 ​

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

shell
php artisan up

📌 備註

您可以透過在 resources/views/errors/503.blade.php 定義自己的範本來客製化預設的維護模式範本。

維護模式與佇列 (Queues) ​

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

維護模式的替代方案 ​

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