萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP include、require、include_once、require_once 差異詳解

前言

PHP 四種引入檔案語句的差異在於「失敗處理方式」與「是否允許重複引入」。理解差異能避免重複定義錯誤、效能浪費與難以除錯的問題。

快速比較表

語句檔案不存在重複引入回傳值適用場景
include警告 (E_WARNING),繼續執行允許,每次都執行成功回傳 1,失敗 false模板、可選元件、條件式載入
require致命錯誤 (E_COMPILE_ERROR),停止執行允許,每次都執行成功回傳 1,失敗不回傳核心類別、必要設定、自動載入
include_once警告,繼續執行忽略,只執行一次成功 1,已載入 true,失敗 false函式庫、類別定義、避免重複定義
require_once致命錯誤,停止執行忽略,只執行一次成功 1,已載入 true,失敗不回傳核心類別庫、單例服務、設定檔

詳細行為差異

1. 錯誤處理

<?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 "不會執行";

2. 重複引入

<?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,不重複執行

3. 回傳值用法

<?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 版本需檢查已載入清單,極微量較慢 (納秒級),可忽略。
  • 大型專案請使用 Composer PSR-4 自動載入,完全避免手動 include/require。
  • OpCache 啟用後,編譯後的 opcode 會快取,重複引入檢查極快。

常見錯誤與陷阱

  1. 巢狀引入路徑錯誤:A include B,B include C,路徑以 B 為基準而非 A。解決:皆用 __DIR__。
  2. BOM 標頭導致輸出:UTF-8 with BOM 檔案被 include 會輸出隱形字元,破壞 JSON/API 回應。解決:儲存為 UTF-8 without BOM。
  3. 條件式 require_once:在 if 區塊中 require_once 可能導致類別未定義。類別定義檔請無條件載入。

現代 PHP 專案建議

  1. 採用 Composer 自動載入 (PSR-4),棄用手動 include/require。
  2. 唯一需手動引入:vendor/autoload.php、框架啟動檔、極少數不支援自動載入的舊庫。
  3. 模板檔案使用 include (允許重複渲染局部視圖)。
  4. 核心設定、服務提供者使用 require_once。

總結

記住核心口訣:「require 必須有,include 可選擇;_once 只有一次」。現代開發以 Composer 自動載入為主,手動引入僅用於邊界情況。

copyright © 萬盛學電腦網 all rights reserved