PHP 專案模組化的核心在於檔案引用，四大指令 require、require_once、include、include_once 雖功能相似，但錯誤處理與重複引用行為截然不同，選擇錯誤會導致難以追蹤的 Bug。
| 指令 | 找不到檔案 | 重複引用同一檔案 | 適用場景 |
|---|---|---|---|
require | Fatal Error，腳本立即終止 | 每次都引用，可能導致函式/類別重複定義錯誤 | 核心設定檔、必要函式庫、缺失即無法繼續的檔案 |
require_once | Fatal Error，腳本立即終止 | 僅引用一次，後續忽略 | 最推薦：類別定義、函式庫、設定檔、避免重複定義 |
include | Warning (警告)，腳本繼續執行 | 每次都引用 | 選用性模板、廣告區塊、缺失不影響主流程的片段 |
include_once | Warning (警告)，腳本繼續執行 | 僅引用一次 | 選用性類別/函式庫、避免重複定義但允許缺失 |
<?php
// 推薦寫法：無括號、單引號、require_once
require_once 'config.php';
require_once 'functions.php';
require_once 'classes/User.php';
// 絕對路徑更安全 (避免 include_path 攻擊)
require_once __DIR__ . '/../config/database.php';
// 條件式引用 (罕見，慎用)
if ($need_api) {
include 'api/client.php';
}
?>require_once：現代 PHP 專案 (Composer/PSR-4) 雖以自動載入為主，但引導檔、設定檔仍建議 require_once，確保缺失即報錯、不重複定義。__DIR__、__FILE__、dirname(__FILE__) 組合路徑，不依賴 include_path，安全且效能佳。_once 版本或重構為函式/類別。.php；僅輸出 HTML 片段 .phtml 或 .tpl.php；設定檔 .config.php 或 .env.php。| 錯誤現象 | 原因 | 解決 |
|---|---|---|
| Fatal error: Cannot redeclare function... | require/include 重複引用同一函式定義檔 | 改用 require_once/include_once |
| Warning: include(xxx.php): failed to open stream | 路徑錯誤、檔案不存在、權限不足 | 檢查相對/絕對路徑、檔案存在、open_basedir 限制 |
| Headers already sent | 引用檔案前有輸出 (含 BOM、空白行) | 引用移至最頂端、移除 BOM、關閉輸出緩衝 |
| Class 'X' not found | 自動載入未註冊、命名空間不符、檔案未引用 | 檢查 Composer autoload.php、命名空間對應、手動 require_once |
// composer.json
{
"autoload": {
"psr-4": {
"App\\": "src/"
},
"files": ["src/helpers.php"]
}
}
// 執行 composer dump-autoload 後
require_once __DIR__ . '/vendor/autoload.php'; // 單一入口，所有類別/函式自動載入
use App\Models\User;
$user = new User();require_once 僅保留於 vendor/autoload.php、環境設定檔、非 PSR-4 相容的第三方庫。掌握四大引用指令差異與最佳實踐，能避免 80% 的「找不到類別/函式重複定義/Headers already sent」經典 PHP 痛點。
