PHP 提供四個檔案引入語句:include、include_once、require、require_once。它們在失敗處理、重複引入檢查、編譯時期/執行期行為上有關鍵差異。本文詳細對比並給出選擇指南與現代自動載入替代方案。
| 語句 | 失敗後果 | 重複引入 | 處理階段 | 典型用途 |
|---|---|---|---|---|
include | Warning,腳本繼續執行 | 每次都引入 | 執行期 | 模板、可選配置、條件式引入 |
include_once | Warning,腳本繼續 | 僅引入一次 | 執行期 | 函式庫、類別定義、防止重複定義錯誤 |
require | Fatal Error,腳本終止 | 每次都引入 | 編譯期 (靜態) | 核心配置、必要依賴、啟動檔案 |
require_once | Fatal Error,腳本終止 | 僅引入一次 | 編譯期 (靜態) | 類別/介面/Trait 定義、核心函式庫 |
require/require_once:編譯期處理,PHP 解析腳本時即展開檔案內容。無法在 if 判斷中動態決定路徑(路徑可用變數,但邏輯分支不影響是否編譯)。include/include_once:執行期處理,執行到該行才引入。可用於條件式引入(如依語系載入不同語系檔)。引入檔案繼承呼叫處的變數作用域:
vars.php 內的程式碼視同寫在 include 該行位置。
'value']; ?>
// 主程式
$result = include 'return.php'; // $result = ['config' => 'value']
$result = require 'return.php'; // 同上
若被引入檔無 return,成功引入回傳 1 (int)。
require_once(必須載入、不可重複、缺失即終止)。require_once(防止 "Cannot redeclare class" 錯誤)。include(缺失不應中斷整頁、可條件式載入)。include_once 或 require_once(視重要性)。require_once 效能成本
優勢:零手動引入、命名空間對應目錄結構、開發/生產環境一致、支援類別別名、最佳化載入順序。
spl_autoload_register() 自訂自動載入 (無 Composer 專案)vendor/autoload.php,其餘交給自動載入。include + 條件判斷。include,讓模板能存取控制器傳入的區域變數。require_once __DIR__ . '/config/database.php'; 避免相對路徑混淆。@include 抑制錯誤,掩蓋問題難除錯。require_once 用於「不可缺少、不可重複」的核心依賴;include 用於「可選、條件式、模板」的靈活引入。現代 PHP 開發核心依賴交給 Composer PSR-4 自動載入,手動 include/require 僅保留於模板渲染與極少數動態載入場景。理解四者在錯誤等級、重複檢查、處理階段的差異,是寫出穩健 PHP 應用的基礎。