Laravel v12.x 一些微妙的錯誤

在開發以及正式環境中，會出現一些微妙的系統錯誤或 Bug，本文針對這些錯誤或 Bug 提出預防方法和解決方案。

如果文章內容有誤或有所遺漏；想討論文章內容；或有其他事項想聯繫者，歡迎透過電子郵件聯絡（電子郵件地址位於網頁最下方），非常感謝！

找不到檔案、Class Not Found

composer install

如果發生外部套件檔案找不到的錯誤，有可能從版本控制系統更新專案後有再安裝新的套件，但本機尚未安裝，請在終端機/命令列執行 composer install (請執行你使用 Composer 的指令，有時可能是 [php executable path] [php arg] composer|composer.phar install)；或者是因為忘記安裝套件，請執行 composer require [套件名稱] 來安裝套件。

composer dump-autoload

檔案找不到也可能是專案更新了 composer 的自動載入路徑，如果 composer.json 中的 autoload 有更新，嘗試執行 composer dump-autoload。如果有使用 Docker 或是 VM 等架構，請在適當的地方執行指令（例如在 Docker 容器內或是 VM 機器中）。要深入研究的話，請注意 composer.json 中 autoload 和 autoload-dev 的設定，以及 Composer 官方關於 Autoloader optimization 的文件說明。

filesystem / Git submodule

檔案找不到的其他原因可能是專案架構問題，如果使用檔案連結，可能是連結失效；又或者使用類似 Git submodule 的架構但尚未拉取更新。

環境變數以及設定檔（Environment Variables and Configuration）

這裡提到的環境變數是指在 Laravel 專案中使用 env helper function 取得的環境變數。

環境變數優先序

假設我在專案中使用 env('FOO_VAR') 想取得 FOO_VAR 環境變數，但是在外部環境變數以及 .env 檔案中都有設定，那麼會取得哪個環境變數呢？

外部環境變數指的是 Laravel 外部的環境變數，例如：
- 在作業系統上設定的環境變數。
- 執行 php 直譯器上 process 設定的變數。
- Artisan CLI 帶入 `--env` 參數。
- PHP-FPM 設定的環境變數。
- 網頁伺服器傳送給 CGI/FastCGI 的環境變數。

答案是外部環境變數會具有最高優先權。

另外，如果設定了外部環境變數 APP_ENV，會優先尋找 .env.[APP_ENV] 檔案，如果沒有找到，才會尋找 .env 檔案，不會同時讀取兩個檔案。

下表列出優先序的可能情形：

外部環境變數 APP_ENV	外部環境變數 FOO_VAR	.env.tea	.env	env(‘FOO_VAR’)
（未設定）	（未設定）	（無此檔案）	`FOO_VAR=C` ✓	`C`
（未設定）	`FOO_VAR=A` ✓	（無此檔案）	`FOO_VAR=C`	`A`
（未設定）	`FOO_VAR=A` ✓	（無此檔案）	（未設定 FOO_VAR）	`A`
（未設定）	`FOO_VAR=A` ✓	（無此檔案）	（未設定 FOO_VAR）	`A`
`APP_ENV=tea`	（未設定）	（無此檔案）	`FOO_VAR=C` ✓	`C`
`APP_ENV=tea`	（未設定）	（有檔案但未設定）	`FOO_VAR=C` ✓	`C`
`APP_ENV=tea`	（未設定）	`FOO_VAR=B` ✓	`FOO_VAR=C` ✓	`B`
`APP_ENV=tea`	（未設定）	`FOO_VAR=B` ✓	（未設定 FOO_VAR）	`B`
`APP_ENV=tea`	`FOO_VAR=A` ✓	`FOO_VAR=B`	`FOO_VAR=C`	`A`

env helper 函式

建議 env helper 函式只在設定檔（位於專案路徑 config/ 底下的 php 檔）中使用。否則，在正式環境上可能會出現意想不到的 bug。

不要在非 config 檔案外使用 env。

在正式環境中通常會將 config 快取起來（執行 php artisan optimize 或 php artisan config:cache），這會讓 Laravel 不會再去讀取 .env 檔案。

請參考 Laravel 官方文件說明 Configuration Caching。