WordPress WP-Cron 定時任務完整開發手冊：API 詳解、頻率擴展與調試技巧

WordPress 內建的 WP-Cron 是一套基於資料庫的偽定時任務系統，支援循環與單次排程，驅動核心功能如定時發文、版本檢查、清理暫存。本文系統整理所有核心 API、參數詳解、頻率擴展方法與實戰調試技巧，是主題/外掛開發者的必備參考。

核心概念

• 觸發機制：任務存入 wp_options 表 cron 選項，每次 HTTP 請求檢查到期任務並執行。
• 時間偏差：低流量站點執行時間可能延遲數分鐘至數小時；高流量或配置系統 Cron 可達秒級精度。
• 鉤子驅動：任務本質是註冊一個 Action Hook，到期時觸發 do_action( $hook, $args )。

完整 API 速查表

關鍵參數詳解

• $timestamp (int, 必填)：首次執行時間戳，**必須使用 current_time('timestamp') 而非 time()**，以兼容時區設置。
• $recurrence (string, 必填)：頻率標識，預設 'hourly'(3600s)、'twicedaily'(43200s)、'daily'(86400s)。
• $hook (string, 必填)：Action Hook 名稱，到期時觸發 do_action($hook, $args)。
• $args (array, 可選)：傳遞給鉤子回調函數的參數陣列。

標準註冊模式（防重複）

// 在插件啟用或主題設置中調用
if ( ! wp_next_scheduled( 'my_daily_cleanup' ) ) {
    wp_schedule_event( current_time( 'timestamp' ), 'daily', 'my_daily_cleanup' );
}

// 掛載實際執行邏輯
add_action( 'my_daily_cleanup', 'my_cleanup_callback' );
function my_cleanup_callback() {
    // 具體業務邏輯：清理過期暫存、發送報表等
    error_log( 'Daily cleanup executed at ' . current_time( 'mysql' ) );
}

自定義執行頻率（突破三種內建限制）

透過 cron_schedules 過濾器添加任意頻率：

function my_custom_cron_schedules( $schedules ) {
    $schedules['weekly'] = array(
        'interval' => 604800,        // 7 * 24 * 60 * 60
        'display'  => __( '每週一次' )
    );
    $schedules['monthly'] = array(
        'interval' => 2592000,       // 30 * 24 * 60 * 60
        'display'  => __( '每月一次' )
    );
    $schedules['quarterly'] = array(
        'interval' => 7776000,       // 90 * 24 * 60 * 60
        'display'  => __( '每季一次' )
    );
    return $schedules;
}
add_filter( 'cron_schedules', 'my_custom_cron_schedules' );

註冊後即可像內建頻率一樣使用：

wp_schedule_event( current_time('timestamp'), 'weekly', 'my_weekly_report' );

調試與運維利器

1. 手動觸發所有到期任務

https://your-site.com/wp-cron.php?doing_wp_cron

瀏覽器訪問即可強制執行，開發調試必備。

2. 禁用偽 Cron，改用系統真 Cron（生產環境推薦）

// wp-config.php
define( 'DISABLE_WP_CRON', true );

# 系統 crontab (每分鐘檢查一次)
* * * * * wget -q -O - "https://your-site.com/wp-cron.php?doing_wp_cron" >/dev/null 2>&1

3. 查看當前所有排程任務（調試外掛）

安裝 WP Crontrol 外掛，後台直觀查看/編輯/運行任務。

4. 記錄執行日誌（排查失敗）

add_action( 'my_task_hook', function() {
    $log = 'Task ran at ' . current_time('mysql') . PHP_EOL;
    file_put_contents( WP_CONTENT_DIR . '/cron-debug.log', $log, FILE_APPEND );
    // 實際業務邏輯...
});

常見坑點避雷指南

掌握 WP-Cron 完整體系，即可構建可靠、可觀測、可擴展的 WordPress 定時任務架構。