使用Carbon Fields在WordPress中无法上传文件至指定文件夹排查

我使用Carbon Fields在WordPress的新增条目页面创建自定义文件字段，期望点击发布条目时，字段中选择的文件能上传到主题目录下的games/{post_id}文件夹中，但文件并未出现在目标文件夹内，其他字段功能正常，目前在Open Server环境中测试，相关代码如下：

add_action('save_post', 'crb_save_post', 10, 3);

function crb_save_post($post_id, $post, $update) {
    if (!$update && defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
        return;
    }

    $file_info = $_FILES['crb_game_files'];

    if ($file_info['error'] === UPLOAD_ERR_OK) {
        $games_folder = get_template_directory() . '/games/';
        $post_folder = $games_folder . $post_id;

        if (file_exists($post_folder)) {
            $target_path = $post_folder . '/' . basename($file_info['name']);
            move_uploaded_file($file_info['tmp_name'], $target_path);
        }
    }
}

add_action('wp_after_insert_post', 'crb_after_insert_post', 10, 3);

function crb_after_insert_post($post_id, $post, $update) {
    if ($post->post_type === 'post') {
        $games_folder = get_template_directory() . '/games/';
        $post_folder = $games_folder . $post_id;

        if (!file_exists($post_folder)) {
            mkdir($post_folder);
        }
    }
}

add_action('after_setup_theme', 'crb_load');
function crb_load() {
    require_once(dirname(dirname(dirname(__DIR__))) . '/vendor/autoload.php');
    \Carbon_Fields\Carbon_Fields::boot();
}

• 钩子执行顺序冲突：save_post钩子触发时机早于wp_after_insert_post。新增文章时，save_post执行时对应post_id的文件夹还未被创建，导致file_exists($post_folder)判断为false，直接跳过文件移动操作。
• $_FILES获取方式错误：Carbon Fields的文件字段并非直接通过$_FILES['crb_game_files']暴露，应该使用官方API获取字段值，比如carbon_get_post_meta($post_id, 'crb_game_files')，直接读取$_FILES可能无法获取正确的上传文件信息。
• 目录权限不足：Open Server环境中，主题目录或games文件夹的写入权限不足，导致无法创建子文件夹或移动上传文件。需确保服务器运行用户（如www-data）对目标目录拥有读写权限。
• 条件判断逻辑缺陷：save_post函数中的if (!$update && defined('DOING_AUTOSAVE') && DOING_AUTOSAVE)逻辑存在冗余，应该优先判断自动保存（无论新增还是更新），优化为if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) return;，避免逻辑混乱导致代码未执行。
• 文件夹创建未配置权限与递归：mkdir($post_folder)未指定权限参数（如0755），且未开启递归创建（第三个参数设为true），若games父文件夹不存在，会导致子文件夹创建失败，后续文件移动也无法执行。
• 未处理文件上传异常：代码未对move_uploaded_file的返回值进行校验，即使文件移动失败也无法排查问题，建议添加错误日志记录，比如if (!move_uploaded_file(...)) error_log('文件移动失败：' . $target_path);。

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