萬盛學電腦網

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

PHP 相對路徑與絕對路徑深度解析:include 陷阱、__DIR__ 魔術常數與最佳實踐

核心問題:相對路徑基準是「執行腳本」而非「當前檔案」

# 目錄結構
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";

總結

  1. 永不使用純相對路徑 (include '../file.php') 於可被多入口引用的檔案中。
  2. 統一使用 __DIR__ 建構絕對路徑,編譯期解析、零效能損耗、跨平台安全。
  3. 專案採用單一入口 + Composer PSR-4 自動載入,**徹底消除手動 include/require 類別檔案**。
  4. 資源檔案路徑集中管理 (常數/設定檔/路徑解析函式),避免硬編碼散落。
  5. 用戶輸入路徑嚴格白名單 + realpath 邊界檢查,防禦目錄遍歷。
copyright © 萬盛學電腦網 all rights reserved