核心問題:相對路徑基準是「執行腳本」而非「當前檔案」
# 目錄結構
project/
├── a.php // 執行入口
├── b.php // 定義常數
└── c/
└── d.php // include '../b.php'
# a.php
# c/d.php
根因:PHP include/require 的相對路徑**以「啟動腳本所在目錄」 (CWD) 為基準**,而非「當前被 include 的檔案目錄」。
解決方案:使用 __DIR__ 魔術常數 (PHP 5.3+)
<?php
// c/d.php - 修正版
include __DIR__ . '/../b.php'; // __DIR__ = /project/c
// 解析為 /project/c/../b.php = /project/b.php ✅
// 更安全:檢查檔案存在
$file = __DIR__ . '/../b.php';
if (!is_file($file)) throw new \RuntimeException("File not found: $file");
include $file;
__DIR__ vs dirname(__FILE__)
| 特性 | __DIR__ | dirname(__FILE__) |
| PHP 版本 | 5.3.0+ | 全版本 |
| 效能 | 編譯期常數,極快 | 函數呼叫,略慢 |
| 可讀性 | 語意清晰 | 較冗長 |
| 建議 | **首選** | 舊專案相容 |
路徑處理最佳實踐模式
1. 專案根目錄常數 (入口檔定義)
<?php
// public/index.php (唯一入口)
define('ROOT_PATH', __DIR__ . '/..'); // 專案根目錄
define('APP_PATH', ROOT_PATH . '/app');
define('CONFIG_PATH', ROOT_PATH . '/config');
define('PUBLIC_PATH', __DIR__);
// 自動載入
require_once ROOT_PATH . '/vendor/autoload.php';
2. 統一路徑解析函式
<?php
function path(string $relative, string $base = ROOT_PATH): string {
$full = $base . '/' . ltrim($relative, '/');
$real = realpath($full);
if ($real === false) {
throw new \InvalidArgumentException("Path not found: $full");
}
// 安全性:防止目錄遍歷攻擊跳出基礎目錄
if (strpos($real, realpath($base)) !== 0) {
throw new \SecurityException("Path traversal attempt: $relative");
}
return $real;
}
// 使用
include path('config/database.php');
$template = file_get_contents(path('views/layout.html'));
3. Composer 自動載入:根本不需要手動 include
# composer.json
{
"autoload": {
"psr-4": {
"App\\": "app/"
}
}
}
# 之後直接 use
use App\Models\User;
use App\Services\Payment\Gateway;
// 完全不需要 include/require 任何類別檔案
常見場景路徑處理對照表
| 場景 | 錯誤寫法 | 正確寫法 | 說明 |
| include 同目錄檔案 | include 'config.php'; | include __DIR__ . '/config.php'; | 避免 CWD 不同導致找不到 |
| include 上層目錄 | include '../config.php'; | include __DIR__ . '/../config.php'; | 同上 |
| 讀取資源檔 (圖片/設定) | file_get_contents('data.json') | file_get_contents(__DIR__ . '/../data.json') | CLI 執行時 CWD 可能不同 |
| 上傳檔案儲存路徑 | move_uploaded_file($tmp, 'uploads/' . $name) | move_uploaded_file($tmp, STORAGE_PATH . '/uploads/' . $name) | 定義 STORAGE_PATH 常數 |
| CLI 腳本讀取專案配置 | require 'config.php'; | require __DIR__ . '/../config.php'; | CLI 執行目錄不固定 |
Windows 路徑分隔符相容性
<?php
// PHP 內建常數自動適配
DIRECTORY_SEPARATOR; // Windows: \ Linux: /
PATH_SEPARATOR; // Windows: ; Linux: :
// 實務:使用 DIRECTORY_SEPARATOR 或直接用正斜線 (PHP 內部自動轉換)
$path = __DIR__ . '/../config.php'; // Windows/Linux 皆可用
$path = __DIR__ . DIRECTORY_SEPARATOR . '..' . DIRECTORY_SEPARATOR . 'config.php'; // 顯式
安全性:防止路徑遍歷攻擊
<?php
// ❌ 危險:用戶輸入直接拼接
include $_GET['page'] . '.php'; // ../../etc/passwd
// ✅ 安全:白名單驗證 + realpath 限制
$allowed = ['home', 'about', 'contact'];
$page = $_GET['page'] ?? 'home';
if (!in_array($page, $allowed, true)) $page = 'home';
include __DIR__ . "/pages/{$page}.php";
總結
- 永不使用純相對路徑 (
include '../file.php') 於可被多入口引用的檔案中。
- 統一使用
__DIR__ 建構絕對路徑,編譯期解析、零效能損耗、跨平台安全。
- 專案採用單一入口 + Composer PSR-4 自動載入,**徹底消除手動 include/require 類別檔案**。
- 資源檔案路徑集中管理 (常數/設定檔/路徑解析函式),避免硬編碼散落。
- 用戶輸入路徑嚴格白名單 + realpath 邊界檢查,防禦目錄遍歷。