PHP 四種引入檔案語句的差異在於「失敗處理方式」與「是否允許重複引入」。理解差異能避免重複定義錯誤、效能浪費與難以除錯的問題。
| 語句 | 檔案不存在 | 重複引入 | 回傳值 | 適用場景 |
|---|---|---|---|---|
include | 警告 (E_WARNING),繼續執行 | 允許,每次都執行 | 成功回傳 1,失敗 false | 模板、可選元件、條件式載入 |
require | 致命錯誤 (E_COMPILE_ERROR),停止執行 | 允許,每次都執行 | 成功回傳 1,失敗不回傳 | 核心類別、必要設定、自動載入 |
include_once | 警告,繼續執行 | 忽略,只執行一次 | 成功 1,已載入 true,失敗 false | 函式庫、類別定義、避免重複定義 |
require_once | 致命錯誤,停止執行 | 忽略,只執行一次 | 成功 1,已載入 true,失敗不回傳 | 核心類別庫、單例服務、設定檔 |
<?php
// include: 產生 Warning,腳本繼續
include 'missing.php'; // Warning: Failed opening 'missing.php'...
echo "繼續執行"; // 會執行
// require: 產生 Fatal Error,腳本中止
require 'missing.php'; // Fatal error: Failed opening required 'missing.php'...
echo "不會執行";
<?php
// a.php
$var = 'first';
echo "a.php loaded\n";
// main.php
include 'a.php'; // 輸出 "a.php loaded", $var = 'first'
include 'a.php'; // 再次輸出 "a.php loaded", $var 重新賦值
include_once 'a.php'; // 輸出 "a.php loaded"
include_once 'a.php'; // 無輸出,回傳 true,不重複執行
<?php
// config.php
return ['db' => ['host' => 'localhost', 'name' => 'test']];
// 使用
$config = include 'config.php'; // $config = ['db' => ...]
$config2 = require 'config.php'; // 相同
// include_once/require_once 第二次呼叫回傳 true (非陣列)
$first = include_once 'config.php'; // 陣列
$second = include_once 'config.php'; // true (布林)
<?php
// 錯誤:相對路徑受當前工作目錄影響
include '../config.php';
// 正確:使用 __DIR__ (當前檔案目錄) 或 __FILE__ (當前檔案完整路徑)
require_once __DIR__ . '/../config.php';
// Composer 自動載入 (現代專案標準)
// composer.json: "autoload": { "psr-4": { "App\\": "src/" } }
// 然後只需:
require_once __DIR__ . '/vendor/autoload.php';
_once 版本需檢查已載入清單,極微量較慢 (納秒級),可忽略。include/require。__DIR__。if 區塊中 require_once 可能導致類別未定義。類別定義檔請無條件載入。vendor/autoload.php、框架啟動檔、極少數不支援自動載入的舊庫。include (允許重複渲染局部視圖)。require_once。記住核心口訣:「require 必須有,include 可選擇;_once 只有一次」。現代開發以 Composer 自動載入為主,手動引入僅用於邊界情況。