php vendor 不存在造成 500 Error

| 2026-05-292026-05-29

如果 vendor/ 目錄一直都不存在，那這支 API 應該從第一天起就直接炸 500 錯誤，而不是「最近才壞掉」。

不過，在 IIS 這種 Windows 環境下，「原本好好的，突然變 500」 通常有兩種最大的可能性：

有人更新了代碼（例如新增了套件），但伺服器端沒有同步執行 composer update 或 composer install，導致 autoload 找不到新類別。
權限問題或 PHP 設定跑掉了（Windows 更新或 IIS 重啟有時會搞鬼）。

不論是哪種情況，我們都可以直接進 Windows Server 確認 vendor 的狀態並進行修復。以下是具體的檢查與安裝步驟：

步驟一：檢查 `vendor` 目錄是否存在與權限

遠端連線 (RDP) 登入你的 Windows Server。
開啟 檔案總管，導向到你 IIS 網站的實體路徑（例如 C:\inetpub\wwwroot\your-project\）。
檢查是否存在 vendor 資料夾：
- 如果不存在： 代表真的沒安裝，必須補跑安裝（見步驟二）。
- 如果存在： 點進去看看有沒有 autoload.php。如果有，請右鍵點擊 vendor 資料夾 -> 內容 -> 安全性，確認 IIS 的讀取權限（通常是 IIS_IUSRS 或 IUSR）沒有被搞丟。

步驟二：在 Windows Server 上安裝/執行 Composer

如果確定需要執行 composer install，請依照以下步驟在伺服器上操作：

1. 確認伺服器是否有安裝 Composer

開啟伺服器的 Command Prompt (CMD) 或 PowerShell，輸入：

Bash

composer --version

有顯示版本： 太棒了，可以直接用。
顯示找不到指令： 代表伺服器沒裝 Composer。請到 Composer 官網下載 Composer-Setup.exe 並直接在伺服器上執行安裝。安裝過程中它會自動偵測你 IIS 目前使用的 php.exe 路徑。

2. 執行安裝或更新指令

在 CMD / PowerShell 中，切換到你的專案根目錄（api.php 所在目錄的上一層，也就是看得到 composer.json 的那層）：

PowerShell

# 切換到專案目錄 (路徑請根據實際狀況修改)
cd C:\inetpub\wwwroot\your-project

# 如果 vendor 完全不存在，或者你想嚴格還原當初測試成功的套件版本：
composer install --no-dev --optimize-autoloader

# 如果 vendor 存在，但懷疑是有人加了新套件沒同步：
composer update --no-dev --optimize-autoloader

💡 小提示： --no-dev 可以避免把開發用的測試套件（如 PHPUnit）裝到生產環境，--optimize-autoloader 則能提升 PHP 在 IIS 上的效能。

步驟三：如果 `vendor` 沒問題，如何抓出真正的 500 錯誤原因？

如果跑完 Composer 還是 500，或者發現 vendor 本來就是好的，那就必須叫 IIS 把隱藏的錯誤訊息吐出來，別再抓瞎了：

1. 修改 `web.config` 顯示詳細錯誤

在專案根目錄下找到（或建立）web.config 檔案，確保 <system.webServer> 區段內有以下設定，這樣 IIS 才會把 PHP 的白畫面或詳細報錯傳回給瀏覽器：

XML

<configuration>
  <system.webServer>
    <httpErrors errorMode="Detailed" />
  </system.webServer>
</configuration>

2. 檢查 PHP 錯誤日誌 (php_errors.log)

開啟你伺服器上的 php.ini 檔案，搜尋以下兩行，確認它們沒有被註解（拿掉前面的 ;）：

Ini, TOML

log_errors = On
error_log = "C:\inetpub\temp\PHP_errors.log" ; (或者是你指定的任何路徑)

修改後記得去 IIS 管理員 (IIS Manager) 重新啟動網站，然後直接去該路徑打開 log 檔案。裡面絕對會清清楚楚寫著到底是哪一行程式碼（例如 Fatal error: Class '...' not found in api.php on line 10）導致 500 錯誤的！

破案了！你貼出的這段 autoload.php 原始碼，直接把最關鍵的線索攤在陽光下了。

請注意這一段程式碼：

PHP

if (PHP_VERSION_ID < 50600) {
    if (!headers_sent()) {
        header('HTTP/1.1 500 Internal Server Error');
    }
    $err = 'Composer 2.3.0 dropped support for autoloading on PHP <5.6 ... Aborting.';
    // ...
    throw new RuntimeException($err);
}

這意味著：如果這台伺服器目前的 PHP 版本低於 5.6（例如 5.5, 5.4 甚至更舊），Composer 就會直接中斷執行，並主動噴出一個 500 Internal Server Error！

根據你提供的目錄列表，vendor 資料夾跟裡面的套件確實都存在（最後更新時間停在 2025 年 11 月左右）。這代表問題不是缺檔案，而是以下兩種可能性最高：

可能性 1：這台 IIS 伺服器的 PHP 版本低於 5.6

如果最近有人動過 IIS 的 PHP 版本設定（例如降級、或者是處理了其他網站導致預設 PHP 版本跑掉），只要當前執行的 PHP 版本小於 5.6，就會完美觸發這個 500 錯誤。

如何驗證：在 D:\your-project\ 下建立一個臨時的 test.php，內容寫：PHP<?php phpinfo(); 在瀏覽器打開這個網頁，確認最上方顯示的 PHP Version 是多少。如果是 5.5 以下，你就找到兇手了！請將 IIS 的 PHP 版本切換回 7.x 或 8.x。

可能性 2：代碼更新了，但 `vendor` 卻是舊的（2025年的遺物）

你看一下目錄列表，大部份套件的日期都停在 2025/09 或 2025/11。

如果最近（2026年）有人更新了 main 分支的程式碼，並在 composer.json 裡面新增了套件、或者是升級了某些套件，但伺服器上的 vendor 資料夾卻一直停留在半年前的舊狀態。

當 api.php 想要調用新版程式碼或新套件時，就會因為舊的 vendor 找不到類別而直接崩潰（500 錯誤）。

如何修正：直接在伺服器上同步更新 vendor。
1. 開啟 CMD 或 PowerShell。
2. 切換到專案根目錄：PowerShellcd D:\your-project
3. 執行更新指令（讓 vendor 同步成目前 composer.json 要求的最新狀態）：PowerShellcomposer install --no-dev --optimize-autoloader (如果沒有安裝 composer 指令，請參考前一次回覆下載安裝，或直接把開發環境整包最新、能跑的 vendor 資料夾打包，覆蓋到伺服器的 D:\portal-backend\backend\vendor)

總結你的下一步

先檢查 phpinfo()，確定 PHP 版本大於 5.6。
只要版本沒問題，直接在 D:\your-project 底下重新跑一次 composer install。這有 90% 的機率能直接解決這個最近才出現的 500 錯誤！

Max的程式語言筆記