跨平台相容的根目錄路徑解析技巧

在 PHP 專案中引入檔案時，使用相對路徑容易因執行入口不同而失效。掌握取得「網站根目錄」與「當前腳本目錄」的可靠方法，能避免部署上線時的路徑錯誤。

方法一：$_SERVER['DOCUMENT_ROOT']（Web 根目錄）

$webRoot = $_SERVER['DOCUMENT_ROOT'];
// 適用：直接對應虛擬主機設定的 DocumentRoot
// 注意：CLI 模式下不可用

方法二：dirname(__FILE__) / __DIR__（當前腳本目錄）

PHP 5.3+ 可直接使用魔術常數 __DIR__，等同 dirname(__FILE__)。

// 引入同目錄下的檔案
include_once __DIR__ . '/config.php';

// 專案根目錄常見做法：假設此檔案在 /app/bootstrap.php
define('APP_ROOT', dirname(__DIR__));  // 往上一層
include_once APP_ROOT . '/vendor/autoload.php';

方法三：定義專案基礎路徑常數（推薦放在入口檔）

<?php
// 統一路徑分隔符為 /，兼容 Windows 與 Linux
define('BASE_PATH', rtrim(str_replace('\\', '/', realpath(__DIR__ . '/')), '/') . '/');

echo BASE_PATH;  // 輸出範例：/var/www/html/ 或 E:/www/project/

方法四：取得網站 URL 根路徑（前端資源引用）

$protocol = (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off') ? 'https' : 'http';
$host = $_SERVER['HTTP_HOST'];
$scriptName = $_SERVER['SCRIPT_NAME'];
$baseUrl = $protocol . '://' . $host . dirname($scriptName) . '/';

echo $baseUrl;  // 例：https://example.com/project/

跨平台注意事項

• 路徑分隔符：Windows 使用 \，Linux/macOS 使用 /。PHP 內建函數多接受 /，建議統一用 DIRECTORY_SEPARATOR 常數或手動 str_replace('\\', '/', $path)。
• 大小寫敏感：Linux 區分大小寫，Windows 不區分。開發時嚴格遵循實際檔案大小寫，避免上線後找不到檔案。
• CLI 執行：排程腳本（cron）執行時 $_SERVER['DOCUMENT_ROOT'] 不存在，務必使用 __DIR__ 為基準。

最佳實踐建議

1. 在專案單一入口檔（如 index.php）定義 ROOT_PATH、APP_PATH 等常數。
2. 所有 include/require 使用絕對路徑常數拼接。
3. 前端 CSS/JS/圖片引用使用 $baseUrl 變數輸出。
4. 佈署時只需修改入口檔常數定義，不需動到業務邏輯程式碼。