PHP 路徑處理最佳實踐：捨棄相對路徑，擁抱絕對路徑常數

推薦架構：單一入口初始化檔

建立 initialize.php 放在專案根目錄，所有入口（index.php、api.php、cli.php、cron.php）第一行只需 require_once __DIR__ . '/initialize.php';。

<?php
// initialize.php
// 1. 定義核心路徑常數（絕對路徑）
defined('DS')       ? null : define('DS', DIRECTORY_SEPARATOR);
defined('SITE_ROOT') ? null : define('SITE_ROOT', __DIR__); // 專案根目錄
defined('LIB_PATH')  ? null : define('LIB_PATH', SITE_ROOT . DS . 'includes');
defined('CONFIG_PATH')? null : define('CONFIG_PATH', SITE_ROOT . DS . 'config');
defined('PUBLIC_PATH')? null : define('PUBLIC_PATH', SITE_ROOT . DS . 'public');
defined('VENDOR_PATH')? null : define('VENDOR_PATH', SITE_ROOT . DS . 'vendor');

// 2. 載入 Composer 自動載入（若使用）
if (file_exists(VENDOR_PATH . DS . 'autoload.php')) {
    require_once VENDOR_PATH . DS . 'autoload.php';
}

// 3. 載入核心設定檔
require_once CONFIG_PATH . DS . 'config.php';      // 資料庫、快取、第三方金鑰等
require_once CONFIG_PATH . DS . 'database.php';    // 可選分離

// 4. 載入核心函式庫
require_once LIB_PATH . DS . 'functions.php';      // 專案通用 helper

// 5. 初始化核心服務（依賴順序：Session → DB → Model/Service）
require_once LIB_PATH . DS . 'session.php';
require_once LIB_PATH . DS . 'database.php';       // 建立 PDO/mysqli 連線

// 6. 載入領域模型/服務類別（可改用自動載入）
require_once LIB_PATH . DS . 'user.php';
require_once LIB_PATH . DS . 'order.php';
// ...

入口檔案範例

<?php
// public/index.php (Web 入口)
require_once __DIR__ . '/../initialize.php';

// 這裡開始寫業務邏輯，所有 require 皆用常數
require_once LIB_PATH . DS . 'controller' . DS . 'UserController.php';
$ctrl = new UserController();
$ctrl->handleRequest();

<?php
// cli/cron_job.php (CLI 入口)
require_once __DIR__ . '/../initialize.php';

// CLI 專用邏輯
require_once LIB_PATH . DS . 'task' . DS . 'SyncOrderTask.php';
$task = new SyncOrderTask();
$task->run();

進階：搭配 Composer PSR-4 完全移除 require

composer.json 設定自動載入：

{
    "autoload": {
        "psr-4": {
            "App\\": "includes/",
            "Config\\": "config/"
        }
    }
}

執行 composer dump-autoload 後，initialize.php 僅需：

require_once VENDOR_PATH . DS . 'autoload.php';
require_once CONFIG_PATH . DS . 'config.php';
// 其餘類別自動載入，零 require

常見錯誤與修正

總結

1. 唯一真理來源：專案根目錄 __DIR__ 衍生所有路徑常數。
2. 集中管理：initialize.php 統一定義、載入順序、環境差異。
3. 跨平台：DIRECTORY_SEPARATOR 吸收 /、\ 差異。
4. 現代化：併用 Composer PSR-4，徹底告別 require_once 攻城獅。

遵循此架構，專案可在 Windows 開發、Linux 容器、Serverless 函式、多入口（Web/CLI/Queue）間零修改遷移，大幅降低部署風險與維護成本。