PHP include 與 require 包含檔案重用代碼完整指南

為什麼需要檔案包含？

當多個頁面共用相同程式碼 (資料庫連線、頁首頁尾、函式庫、設定檔) 時，使用檔案包含可避免重複撰寫，維護時只需修改一處。

四大包含函式對比

實務範例

場景一：靜態版權資訊 - 使用 require

<!DOCTYPE html>
<html>
<head><title>網站標題</title></head>
<body>
    <div id="content">主要內容區塊</div>
    <footer>
        <?php require __DIR__ . '/includes/copyright.php'; ?>
    </footer>
</body>
</html>

copyright.php：

<?php // 必須包含 PHP 標籤，否則會直接輸出原始碼
echo '© 2024 My Website. All rights reserved.';
?>

場景二：函式庫載入 - 使用 include_once

<?php
include_once __DIR__ . '/lib/database.php';
include_once __DIR__ . '/lib/functions.php';

// 現在可以直接使用庫中的函式
$conn = db_connect();
$users = get_users($conn);
?>
<!DOCTYPE html>...

場景三：條件式載入不同樣板 - 使用 include

<?php
$template = isset($_GET['tpl']) ? $_GET['tpl'] : 'default';
$allowed = ['default', 'mobile', 'print'];

if (in_array($template, $allowed)) {
    include "templates/{$template}.php";
} else {
    include "templates/default.php";
}
?>

關鍵技術細節

1. 變數作用域

包含檔案會繼承呼叫處的變數作用域：

<?php
$var = '外部變數';
include 'inc.php';  // inc.php 內可直接存取 $var
?>

2. 路徑解析最佳實務

• 使用 __DIR__ 魔術常數 (PHP 5.3+) 取得當前檔案目錄
• 避免相對路徑，防止包含層級改變導致路徑失效
• 定義專案根目錄常數：define('ROOT', __DIR__);

3. 安全性考量

• 敏感資訊隔離：資料庫密碼、API 金鑰等放在網站根目錄外部，require '/path/outside/webroot/config.php';
• 副檔名保護：包含檔建議用 .php 副檔名，並確保伺服器解析 PHP，防止直接訪問洩露原始碼
• 防止目錄遍歷：動態包含時嚴格驗證檔名，使用白名單機制

include vs require 選擇決策樹

1. 檔案是核心必要元件？ → require / require_once
2. 檔案包含類別/函式定義？ → _once 版本
3. 條件式/動態載入樣板？ → include
4. 允許頁面部分載入失敗？ → include

效能提示

• APC/OPcache 會快取編譯後的 opcode，require_once 在啟用快取時效能差異可忽略
• 避免在迴圈中包含檔案，移至迴圈外或使用自動載入器
• 大型專案建議使用 Composer PSR-4 自動載入，取代手動 include/require