wp_schedule_single_event()返回成功但未创建wp-cron任务问题排查

核心问题说明 #

wp_schedule_single_event()返回true仅代表参数格式合法、函数执行流程无错误，不代表任务一定会被成功存储或触发——这是很多开发者容易误解的逻辑。结合你的场景，以下是具体排查和解决方向：

1. 先确认时间戳的合法性 #

如果传入的时间戳是过去的时间，WP Cron会直接丢弃该任务，但函数依然返回true。比如你代码中第二个任务用了time - 86400，若这个时间早于当前时间，任务不会被创建，但函数不会返回false。

建议在调度前增加时间校验：

$current_time = time();
// 检查目标时间是否在未来
if ($target_time <= $current_time) {
    write_log('Skipped scheduling: target time (' . $target_time . ') is in the past');
    return;
}
$success = wp_schedule_single_event($target_time, 'hook_addProductsExpired', array(get_current_user_id()));

2. 理解WP Cron的触发机制局限 #

WP Cron不是系统级定时任务，它依赖网站访问来触发任务执行。如果网站长时间没有访客，定时任务会延迟甚至“丢失”。解决方法：

• 配置系统Cron（如Linux crontab）定期访问wp-cron.php?doing_wp_cron，替代默认的访问触发
• 在wp-config.php中添加define('DISABLE_WP_CRON', true);，禁用自动触发，避免访问冲突

3. 排查重复任务的覆盖逻辑 #

当你用相同钩子+相同参数再次调度任务时，WP Cron会覆盖已存在的同类型任务，但wp_schedule_single_event()依然返回true。如果业务不允许覆盖，可在调度前检查任务是否存在：

// 检查任务是否已存在
$existing_run_time = get_next_scheduled('hook_addProductsExpired', array(get_current_user_id()));
if ($existing_run_time) {
    write_log('Event already scheduled for user ' . get_current_user_id() . ' at ' . $existing_run_time);
} else {
    $success = wp_schedule_single_event($time, 'hook_addProductsExpired', array(get_current_user_id()));
}

4. 扩展日志维度，捕捉隐性问题 #

现有日志仅记录调度动作，建议增加以下日志：

• 调度时的当前时间戳，对比目标时间是否合理
• 调度后主动查询任务是否存在
• 钩子回调函数的执行日志（确认任务是否被触发）

示例日志代码：

$current_ts = time();
write_log('User ' . get_current_user_id() . ' | Current time: ' . $current_ts . ' | Target time: ' . $time);

$success = wp_schedule_single_event($time, 'hook_addProductsExpired', array(get_current_user_id()));
// 调度后验证任务是否存在
$next_run = get_next_scheduled('hook_addProductsExpired', array(get_current_user_id()));
write_log('User ' . get_current_user_id() . ' | Schedule result: ' . ($success ? 'Success' : 'Failed') . ' | Next run: ' . ($next_run ?: 'Not found'));

5. 排查数据库与缓存问题 #

WP Cron任务存储在数据库wp_options表的cron字段中，如果数据库读写异常、或缓存插件缓存了该字段，会导致任务不生效或查询不到：

• 直接查看数据库wp_options表，搜索option_name = 'cron'，确认任务是否存在
• 临时禁用缓存插件，测试问题是否复现
• 检查数据库权限，确保WordPress有读写wp_options表的权限

内容的提问来源于stack exchange，提问作者Jakob Meusburger