在 Linux 透過 crontab 定時執行 PHP 腳本看似簡單，實則暗藏環境變數缺失、工作目錄錯誤、PHP CLI vs FPM 差異、輸出重導向、執行超時等坑點。本文詳細說明正確寫法：#!/usr/bin/php shebang、完整路徑呼叫、載入 .env 設定、鎖檔防重複執行、日誌輪轉、systemd timer 現代替代方案。
#!/usr/bin/php
| 形式 | 範例 | 優缺點 |
|---|---|---|
| 直接呼叫 PHP 二進制 | */5 * * * * /usr/bin/php /opt/scripts/job.php >> /var/log/job.log 2>&1 | 明確、不依賴 shebang、推薦生產環境 |
| 利用 shebang 直接執行 | */5 * * * * /opt/scripts/job.php >> /var/log/job.log 2>&1 | 簡潔、需 chmod +x 且 shebang 正確 |
| 系統 crontab (/etc/crontab) 指定用戶 | */5 * * * * www-data /usr/bin/php /opt/scripts/job.php >> /var/log/job.log 2>&1 | 集中管理、可指定執行身分 |
cron 執行環境極度精簡：PATH=/usr/bin:/bin、無 HOME、無 LANG、無專案專用變數。
putenv() 載入 .env (推薦)
// 見上方核心原則第 2 點
PATH=/usr/local/bin:/usr/bin:/bin
LANG=zh_TW.UTF-8
APP_ENV=production
*/5 * * * * /usr/bin/php /opt/scripts/job.php
#!/bin/bash
# /opt/scripts/run_job.sh
export APP_ENV=production
export LANG=zh_TW.UTF-8
cd /opt/scripts
/usr/bin/php job.php >> /var/log/job.log 2>&1
crontab 僅呼叫 /opt/scripts/run_job.sh。
| 現象 | 原因 | 解決 |
|---|---|---|
| 手動執行正常，cron 不執行 | 環境變數/工作目錄/權限不同 | 腳本加 chdir(dirname(__FILE__))、完整路徑、載入 .env |
| PHP Warning: Module 'xxx' already loaded | cli/php.ini 重複載入擴充 | 檢查 /etc/php/7.x/cli/conf.d/ 去重 |
| 資料庫連線失敗 | PDO DSN 用 localhost → Unix socket，cron 環境無 socket | 改用 127.0.0.1 或指定 unix_socket=/var/run/mysqld/mysqld.sock |
| 輸出亂碼/中文問號 | LANG 未設定 | export LANG=zh_TW.UTF-8 |
| 腳本重複執行 | 上次未結束，cron 再次觸發 | flock 鎖檔 (見核心原則第 4 點) |
| 執行超時被 kill | cron 無內建超時，但系統可能有限制 | set_time_limit()、或用 timeout 300 包裝 |
| 日誌檔案過大 | 無輪轉 | 配置 logrotate 或用 rotatelogs |
# /etc/systemd/system/php-job.service
[Unit]
Description=PHP Scheduled Job
After=network.target mysql.service
[Service]
Type=oneshot
User=www-data
WorkingDirectory=/opt/scripts
ExecStart=/usr/bin/php job.php
StandardOutput=append:/var/log/php-job.log
StandardError=append:/var/log/php-job-error.log
# /etc/systemd/system/php-job.timer
[Unit]
Description=Run PHP Job every 5 minutes
[Timer]
OnBootSec=5min
OnUnitActiveSec=5min
AccuracySec=1s
Persistent=true
[Install]
WantedBy=timers.target
啟用：systemctl daemon-reload && systemctl enable --now php-job.timer
優點：秒級精度、 journald 整合、依賴管理、隨機延遲 RandomizedDelaySec 避免驚群。
/var/log/php-job.log {
daily
rotate 30
compress
delaycompress
missingok
notifempty
create 640 www-data www-data
sharedscripts
postrotate
systemctl reload php-job > /dev/null 2>&1 || true
endscript
}
