PHP include 與 require 差異詳解

程式碼重用是軟體工程核心原則。PHP 提供 include、require、include_once、require_once 四種檔案引入機制，支援模組化開發。理解其差異與適用場景，能避免常見陷阱。

核心差異：錯誤處理行為

基本語法

include 'path/to/file.php';
require 'path/to/file.php';
// 括號可選，但建議省略以區別函數呼叫

引入時會在目標檔案作用域執行代碼，可存取當前變數作用域。

實務應用範例

1. 共用版頭

<!-- header.php -->
<header>
    <nav>
        <a href="/">首頁</a>
        <a href="/products">產品</a>
        <a href="/contact">聯絡我們</a>
    </nav>
</header>

<!-- index.php -->
<!DOCTYPE html>
<html>
<head><title>首頁</title></head>
<body>
    <?php include 'header.php'; ?>
    <main>首頁內容...</main>
    <?php include 'footer.php'; ?>
</body>
</html>

2. 共用選單

<!-- menu.php -->
<ul class="menu">
    <li><a href="/">首頁</a></li>
    <li><a href="/html">HTML 教學</a></li>
    <li><a href="/php">PHP 教學</a></li>
</ul>

<?php include 'menu.php'; ?>

3. 變數共享

<!-- config.php -->
<?php
$siteName = '我的網站';
$adminEmail = 'admin@example.com';
$features = ['blog', 'shop', 'forum'];
?>

<?php
include 'config.php';
echo "<h1>歡迎來到 $siteName</h1>";
echo "管理員信箱：$adminEmail";
?>

路徑解析規則

1. 相對路徑：相對於 執行腳本（而非被引入檔案）的位置
2. 絕對路徑：以 / 開頭或磁碟機代號
3. include_path：php.ini 設定的搜尋路徑，set_include_path() 可動態修改

<?php
// 推薦：使用 __DIR__ 取得當前檔案目錄，構建絕對路徑
require_once __DIR__ . '/../config/database.php';
require_once __DIR__ . '/lib/Database.php';

進階：自動載入器

現代 PHP 專案使用 Composer PSR-4 自動載入，避免手動 require。

<?php
// composer.json
{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

// 執行 composer dump-autoload 後
require_once __DIR__ . '/vendor/autoload.php';

use App\Controller\UserController;
use App\Model\User;

常見陷阱與解決方案

1. 重複引入導致「Cannot redeclare function/class」

解決： 使用 _once 版本，或檢查 function_exists() / class_exists()。

2. 引入路徑錯誤

<?php
// 錯誤：相對於執行腳本
include 'config.php'; // 在 subdir/page.php 中會找不到

// 正確：使用 __DIR__
include __DIR__ . '/../config.php';

3. BOM / 輸出導致 Header 無法發送

被引入檔案開頭有空白、BOM 或輸出，會導致 header()、session_start()、setcookie() 失效。

解決： PHP 純代碼檔案 省略結尾 ?>，避免意外輸出。

4. 變數作用域誤解

<?php
// funcs.php
function getConfig() {
    return $GLOBALS['config']; // 需用 $GLOBALS 或參數傳遞
}

// main.php
$config = ['debug' => true];
include 'funcs.php'; // $config 在此作用域可見
echo getConfig(); // 錯誤：函數內部看不到 $config

效能考量

• require_once 有快取機制（opcache），重複引入極快
• 大量條件式引入可考慮自動載入器
• 避免在迴圈中引入檔案

最佳實踐總結

1. 核心依賴用 require_once：設定、資料庫連線、核心類別
2. 版面元件用 include：header、footer、sidebar、widgets
3. 函數庫/類別定義用 require_once 或 include_once
4. 統一使用絕對路徑：__DIR__ . '/path'
5. 純 PHP 檔案省略 ?>
6. 採用 Composer 自動載入：現代專案標準

善用 include/require 機制，配合自動載入器，能建構清晰、可維護、效能優異的 PHP 專案架構。