設定 - Knowledge of Laravel

簡介

Laravel 框架的設定檔全部放在 config/ 目錄。每個選項都有註解，建議打開檔案來看看可用的選項。在設定檔中，可管理資料庫連線資訊、郵件伺服器資訊、應用程式 URL 與加密金鑰等各種核心設定值。

`about` 指令

透過 about Artisan 指令，可查看應用程式的設定、驅動、環境概要。

php artisan about

若只想查看特定區段，可使用 --only 選項。

php artisan about --only=environment

若要更詳細地查看特定設定檔的值，可使用 config:show 指令。

php artisan config:show database

環境設定（.env）

我們常常需要依執行環境切換設定值。例如在本機與正式環境使用不同的快取驅動。 Laravel 使用 DotEnv PHP 函式庫讓這件事變得簡單。新安裝時，應用程式根目錄會包含定義了常用環境變數的 .env.example，並在安裝流程中自動複製為 .env。

在團隊開發時，建議一併更新 .env.example 並納入版本控制。設定佔位值可以讓其他開發者清楚知道需要哪些環境變數。

環境檔案的安全性

請不要將 .env 檔案提交到版本控制。因為每位開發者或每台伺服器需要不同的設定，且若納入版本庫，出現意外時將導致機密資訊外洩。

不過，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`

要設定含空白的值請以雙引號包起來。

APP_NAME="My Application"

讀取環境變數

.env 檔案內的變數會在請求進來時載入到 $_ENV PHP 超全域變數。在設定檔中可透過 env() 函式取得值。

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

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

取得目前的環境

目前的環境是由 .env 檔案的 APP_ENV 決定。可透過 App Facade 的 environment 方法取得。

use Illuminate\Support\Facades\App;

$environment = App::environment();

也可以傳入參數判斷是否為特定環境。

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

if (App::environment(['local', 'staging'])) {
    // 本機或 staging 環境
}

加密環境檔案

未加密的環境檔案不應存放在版本控制，但 Laravel 提供了加密環境檔案的功能。

加密

若要加密環境檔案，可使用 env:encrypt 指令。

php artisan env:encrypt

執行後，.env 會被加密，加密後的內容會存到 .env.encrypted 檔案。解密金鑰會顯示在指令輸出中，請妥善保存於安全的密碼管理工具。若要指定自己的加密金鑰，可使用 --key 選項。

php artisan env:encrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

所提供的金鑰長度必須與所使用的加密演算法要求的金鑰長度一致。預設會使用需要 32 字元金鑰的 AES-256-CBC。透過 --cipher 選項可以使用加密所支援的任何加密方式。

當應用程式有多個環境檔案，例如 .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...

透過可讀格式，可以在不暴露機密資料的情況下確認有哪些環境變數存在。並且在審核 Pull Request 時，也能不必解密檔案就掌握新增、刪除或變更了哪些變數。在解密環境檔案時，Laravel 會自動判別使用的格式，因此 env:decrypt 指令不需要額外的選項。

使用 --readable 選項時，原本環境檔案中的註解與空行不會包含在加密後的輸出中。

更新可讀的加密檔案

更新可讀的加密環境檔案時，Laravel 會保留未變更的值不動，並移除原始環境檔案中已不存在的變數。

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

若加密檔案不存在則會建立新檔。更新既有檔案時，請指定與建立時相同的加密金鑰與加密演算法。若解密失敗，指令會失敗而不會覆寫既有檔案。若要強制重新加密所有值，可使用 --force 選項。可用於變更加密金鑰，或替換已失效的加密檔案。

php artisan env:encrypt --readable --force --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

解密

若要解密環境檔案，可使用 env:decrypt 指令。此指令需要解密金鑰，Laravel 會從 LARAVEL_ENV_ENCRYPTION_KEY 環境變數取得。

php artisan env:decrypt

也可以透過 --key 選項直接傳入金鑰。

php artisan env:decrypt --key=3UVsEgGVK36XN82KKeyLFMhvosbZN1aF

執行 env:decrypt 指令後，Laravel 會將 .env.encrypted 檔案的內容解密並寫入 .env 檔案。若要使用自訂的加密演算法，可指定 --cipher 選項。

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

當應用程式有多個環境檔案，例如 .env 與 .env.staging，可透過 --env 選項指定要解密的環境名稱。

php artisan env:decrypt --env=staging

若要覆寫既有的環境檔案，請指定 --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/Tokyo');

若要於執行期變更設定值，可使用 Config::set() 或傳入陣列給 config()。

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

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

也提供有型別的取得方法，型別不符時會拋出例外。

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

設定的快取

為提升應用程式效能，可將所有設定檔快取為單一檔案。

php artisan config:cache

此指令會將所有設定選項合併為一個檔案，讓框架能快速載入。

請在正式環境的部署流程中執行 config:cache 指令。本機開發時因為設定會頻繁變動，建議不要執行。

一旦建立快取，.env 檔案將不再於框架處理請求或執行 Artisan 指令時載入。因此 env() 函式僅會回傳系統層級的環境變數。

正因如此，請只在 config/ 目錄的設定檔中呼叫 env() 函式。應用程式其他地方請透過 config() 函式取得設定值。

要清除快取請使用 config:clear 指令。

php artisan config:clear

發布設定檔

Laravel 大部分的設定檔已經發佈於 config/ 目錄，但 cors.php 或 view.php 等部分檔案預設並未發佈。若要發佈尚未發佈的設定檔，可以使用 config:publish 指令。

php artisan config:publish

php artisan config:publish --all

除錯模式

config/app.php 的 debug 選項決定要向使用者顯示多少錯誤資訊。此選項預設遵循 .env 檔案中 APP_DEBUG 環境變數。

在正式環境中，請務必將 APP_DEBUG 設為 false。 若留為 true，可能會將應用程式的機密設定值暴露給終端使用者。

# 本機開發
APP_DEBUG=true

# 正式環境
APP_DEBUG=false

維護模式

當應用程式處於維護模式時，所有請求會顯示自訂視圖。這讓你可以在更新或維護時暫時「停用」應用程式。

啟用維護模式

php artisan down

指定 --refresh 選項時，瀏覽器會於指定秒數後自動重新載入。

php artisan down --refresh=15

--retry 選項會作為 Retry-After HTTP 標頭的值。

php artisan down --retry=60

略過維護模式

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

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

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

php artisan down --with-secret

多台伺服器的維護模式

預設情況下，Laravel 會以檔案為基礎管理維護模式。若為多台伺服器架構，建議使用快取版本。

APP_MAINTENANCE_DRIVER=cache
APP_MAINTENANCE_STORE=database

預先渲染維護視圖

若在部署過程中執行 php artisan down，可能會有使用者在依賴更新期間看到錯誤畫面。可透過 --render 選項預先渲染視圖來避免。

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

也可以在維護模式期間將所有請求重新導向到指定 URL。

php artisan down --redirect=/

停用維護模式

php artisan up

維護模式的預設樣板可透過建立 resources/views/errors/503.blade.php 進行自訂。

若要完全消除停機時間，可以考慮使用如 Laravel Cloud 這類的全託管平台。

下一步

路由

學習連結 URL 與控制器的路由基礎。

開始使用

基礎

請求處理

資料庫

認證

輔助工具與外部通訊

測試與部署

AI 開發輔助

設定

簡介

`about` 指令

環境設定（.env）

環境檔案的安全性

額外的環境檔案

環境變數的型別

讀取環境變數

取得目前的環境

加密環境檔案

加密

可讀的變數名稱

更新可讀的加密檔案

解密

存取設定值

設定的快取

發布設定檔

除錯模式

維護模式

啟用維護模式

略過維護模式

多台伺服器的維護模式

預先渲染維護視圖

停用維護模式

下一步

路由

​簡介

​about 指令

​環境設定（.env）

​環境檔案的安全性

​額外的環境檔案

​環境變數的型別

​讀取環境變數

​取得目前的環境

​加密環境檔案

​加密

​可讀的變數名稱

​更新可讀的加密檔案

​解密

​存取設定值

​設定的快取

​發布設定檔

​除錯模式

​維護模式

​啟用維護模式

​略過維護模式

​多台伺服器的維護模式

​預先渲染維護視圖

​停用維護模式

​下一步

路由

簡介

`about` 指令

環境設定（.env）

環境檔案的安全性

額外的環境檔案

環境變數的型別

讀取環境變數

取得目前的環境

加密環境檔案

加密

可讀的變數名稱

更新可讀的加密檔案

解密

存取設定值

設定的快取

發布設定檔

除錯模式

維護模式

啟用維護模式

略過維護模式

多台伺服器的維護模式

預先渲染維護視圖

停用維護模式

下一步