PHP CLI 模式下 require 路徑錯誤：根因分析與兩大解法

同事回報排程腳本在瀏覽器訪問正常，但命令行執行卻報 require 路徑錯誤。經排查，發現是 CLI 模式下的「當前工作目錄」非腳本所在目錄 導致相對路徑失效。

問題根因

• 瀏覽器請求：Web 伺服器將工作目錄設為腳本所在目錄，相對路徑正常。
• CLI 執行：php /path/to/script.php 的工作目錄是 執行命令時所在的目錄，而非腳本目錄。
• 相對路徑 require '../lib/config.php' 會相對於「命令執行目錄」解析，導致找不到檔案。

解決方案對比

PHP CLI 實用指令速查

# 檢查語法
php -l script.php

# 顯示版本與運行模式
php -v

# 解析並執行檔案
php -f script.php

# 直接執行代碼片段（無需  標籤）
php -r 'echo "hello!";'

# 進入互動模式
php -a

# 顯示模組列表
php -m

# 指定 php.ini 路徑
php -c /path/to/php.ini

# 語法高亮輸出
php -s script.php

# 移除註解與空白輸出
php -w script.php

關鍵環境變數差異

• $_SERVER['SCRIPT_FILENAME']：CLI 下為絕對路徑，可靠。
• __DIR__ / dirname(__FILE__)：永遠指向「當前檔案所在目錄」，最穩健的基準點。
• getcwd()：返回「命令執行時的工作目錄」，CLI 下不可信。

💡 最佳實踐：在所有 CLI 入口腳本（排程、佇列消費者、遷移腳本）頂部統一加入 chdir(__DIR__);，徹底消除路徑困擾。