PHP CLI 模式下 require 路徑錯誤：根因分析與兩種解決方案

PHP CLI 模式下 require 路徑錯誤：根因分析與兩種解決方案

現象：瀏覽器訪問頁面正常，但命令行執行 php script.php 報錯 failed to open stream: No such file or directory，提示 require 找不到文件。

根因：工作目錄 (CWD) 不同

• Web 模式：CWD = 腳本所在目錄 (或 DocumentRoot)，相對路徑基於此解析。
• CLI 模式：CWD = **執行命令時所在的 Shell 目錄**，與腳本物理位置無關。

若腳本用 require '../lib/db.php'，Web 下正常，CLI 下若在 /home/user 執行 php /var/www/script.php，會去找 /home/user/../lib/db.php 導致失敗。

方案一：統一使用絕對路徑 (推薦簡單項目)

<?php
// 使用 __DIR__ 魔術常量 (當前文件所在目錄)
require __DIR__ . '/../lib/db.php';
require __DIR__ . '/config.php';
// 或 define('BASE_PATH', __DIR__); 然後 require BASE_PATH . '/lib/db.php';

• 優點：一勞永逸，不依賴 CWD。
• 缺點：引用鏈長時 (A require B, B require C) 需全部改寫，維護成本高。

方案二：腳本入口強制切換 CWD (推薦複雜項目/遷移舊代碼)

<?php
// 腳本最頂部 (require 之前) 加入：
chdir(dirname(__FILE__)); // PHP 5.3+ 推薦 __DIR__
// 或
chdir(__DIR__);

// 之後所有相對路徑 require 即可正常工作
require 'lib/db.php';
require '../config.php';

• 優點：零修改現有相對路徑代碼，遷移成本極低。
• 缺點：若腳本被 include 到其他 CLI 腳本中，可能影響調用方 CWD (較少見)。

驗證腳本

<?php
// test_cwd.php
echo "CWD: " . getcwd() . "\n";
echo "__DIR__: " . __DIR__ . "\n";
echo "argv[0]: " . $argv[0] . "\n";

分別在不同目錄執行 php /path/to/test_cwd.php 觀察輸出差異。

最佳實踐建議

1. **新項目**：統一使用 __DIR__ / BASE_PATH 絕對路徑，配合 Composer PSR-4 自動加載，徹底告別 require 相對路徑。 2. **舊項目遷移**：入口文件加 chdir(__DIR__) 快速修復，逐步重構為絕對路徑。 3. **定時任務 (crontab)**：命令寫全路徑 cd /var/www/project && php script.php 或腳本內 chdir 雙重保險。 4. **框架入口** (Laravel/ThinkPHP/Yii) 均已在入口文件處理 CWD，開發者無感知。