Linux 下 PHP dirname(__FILE__) 路徑問題解決方案

從 Windows (IIS) 遷移到 Linux (Apache/Nginx) 時，include("文件名") 相對路徑常失效。本文解析 dirname(__FILE__) 解決跨平台包含路徑的原理與最佳實踐。

問題現象

• Windows/IIS：include("config.php") 正常工作
• Linux/Apache：提示「failed to open stream: No such file or directory」

根因分析

Linux 下 Web 根目錄通常為 /home/web/，相對路徑基於執行腳本所在目錄而非包含文件所在目錄。多層包含時工作目錄發生變化，導致路徑解析錯誤。

解決方案

核心技巧：dirname(__FILE__)

<?php
// 當前文件所在目錄絕對路徑
$baseDir = dirname(__FILE__);

// 包含同目錄文件
include $baseDir . '/page.php';

// 包含上級目錄文件
include dirname($baseDir) . '/config.php';

// 多級向上
include dirname(dirname(__FILE__)) . '/lib/common.php';
?>

__FILE__ 魔術常量說明

• 返回當前文件的完整絕對路徑（含文件名）
• 在被包含文件中，返回被包含文件的路徑
• PHP 5.3+ 推薦使用 __DIR__ 等價於 dirname(__FILE__)

最佳實踐模式

1. 定義項目根目錄常量（入口文件）

<?php
// index.php 或 bootstrap.php
define('ROOT_PATH', dirname(__DIR__)); // 項目根目錄
define('APP_PATH', ROOT_PATH . '/app');
define('CONFIG_PATH', ROOT_PATH . '/config');
// ...

2. 統一使用常量包含

include CONFIG_PATH . '/database.php';
require_once APP_PATH . '/models/User.php';

3. Composer 自動加載（現代標準）

// composer.json
{
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    }
}
// 運行 composer dump-autoload
// 僅需在入口引入
require_once __DIR__ . '/vendor/autoload.php';

遷移檢查清單

1. 將所有 include/require 相對路徑改為基於 __DIR__ 或常量
2. 檢查 open_basedir 限制是否包含項目目錄
3. 確認文件權限（Linux 區分大小寫）
4. 驗證 .htaccess / Nginx rewrite 規則

採用 dirname(__FILE__) / __DIR__ 作為路徑基準，是 PHP 跨平台部署的基礎規範。