PHP 8环境下wp_insert_attachment无法工作的问题排查与解决

问题分析 #

你的代码在PHP7.4环境正常，但在PHP8.1中失效，核心问题出在PHP8对函数错误处理的严格性提升，以及部分旧函数的行为变化，导致wp_insert_attachment返回0或错误，最终返回false。

调试步骤（先定位具体错误） #

1. 开启WordPress的日志记录，在wp-config.php中添加：

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

错误会写入wp-content/debug.log，方便查看PHP8抛出的警告或错误。

2. 在代码中添加详细的错误日志输出，替换原有的返回false逻辑：

// 替换download_url的错误处理
if( is_wp_error( $temp_file ) ) {
    error_log('download_url error: ' . $temp_file->get_error_message());
    return false;
}

// 替换$sideload的错误处理
if( ! empty( $sideload[ 'error' ] ) ) {
    error_log('wp_handle_sideload error: ' . $sideload['error']);
    return false;
}

// 替换wp_insert_attachment的错误处理
if( is_wp_error( $attachment_id ) || ! $attachment_id ) {
    if(is_wp_error($attachment_id)){
        error_log('wp_insert_attachment error: ' . $attachment_id->get_error_message());
    } else {
        error_log('wp_insert_attachment failed, attachment_id is 0');
    }
    return false;
}

通过日志可以精准定位是哪一步出错。

修复后的代码（兼容PHP8） #

require_once('../../../../wp-load.php');

function rudr_upload_file_by_url( $image_url ) {
    // 引入必要的WordPress文件处理函数
    require_once( ABSPATH . 'wp-admin/includes/file.php' );
    require_once( ABSPATH . 'wp-admin/includes/image.php' );

    // 下载文件到临时目录
    $temp_file = download_url( $image_url );

    if( is_wp_error( $temp_file ) ) {
        error_log('download_url error: ' . $temp_file->get_error_message());
        return false;
    }

    // 检查临时文件是否存在且可读
    if (!file_exists($temp_file) || !is_readable($temp_file)) {
        error_log('Temporary file not found or unreadable: ' . $temp_file);
        @unlink($temp_file); // 清理临时文件
        return false;
    }

    // 使用WordPress原生函数获取文件类型，替代mime_content_type（兼容PHP8）
    $file_type = wp_check_filetype(basename($image_url), null);

    // 构造文件数组
    $file = array(
        'name'     => basename( $image_url ),
        'type'     => $file_type['type'] ?: mime_content_type( $temp_file ), // 降级处理
        'tmp_name' => $temp_file,
        'size'     => filesize( $temp_file ),
    );

    // 处理文件上传到uploads目录
    $sideload = wp_handle_sideload(
        $file,
        array(
            'test_form'   => false // 不需要检查action参数
        )
    );

    if( ! empty( $sideload[ 'error' ] ) ) {
        error_log('wp_handle_sideload error: ' . $sideload['error']);
        @unlink($temp_file); // 清理临时文件
        return false;
    }

    // 添加到媒体库
    $attachment_data = array(
        'guid'           => $sideload[ 'url' ],
        'post_mime_type' => $sideload[ 'type' ],
        'post_title'     => sanitize_text_field(basename( $sideload[ 'file' ] )), // 清理标题，避免PHP8的字符串处理警告
        'post_content'   => '',
        'post_status'    => 'inherit',
    );

    $attachment_id = wp_insert_attachment(
        $attachment_data,
        $sideload[ 'file' ]
    );

    if( is_wp_error( $attachment_id ) || ! $attachment_id ) {
        if(is_wp_error($attachment_id)){
            error_log('wp_insert_attachment error: ' . $attachment_id->get_error_message());
        } else {
            error_log('wp_insert_attachment failed, attachment_id is 0');
        }
        @unlink($sideload['file']); // 清理已上传的文件
        return false;
    }

    // 更新附件元数据，生成缩略图
    $metadata = wp_generate_attachment_metadata( $attachment_id, $sideload[ 'file' ] );
    wp_update_attachment_metadata( $attachment_id, $metadata );

    return $attachment_id;
}

$test_url = 'https://www.mundo-flamenco.com/typo3temp/GB/a5ddd34bdf.png'; 
$res = rudr_upload_file_by_url($test_url); 
echo $res; 
?>

关键修复点说明 #

• 替换mime_content_type为wp_check_filetype：PHP8中mime_content_type对无效文件会抛出警告，wp_check_filetype是WordPress原生函数，兼容性更好，能正确识别文件MIME类型。
• 增加临时文件存在性检查：PHP8中对不存在的文件调用filesize或mime_content_type会触发致命错误，提前检查可避免这种情况。
• 添加文件清理逻辑：在出错时清理临时文件和已上传的文件，避免服务器冗余文件堆积。
• 标题内容清理：使用sanitize_text_field处理附件标题，避免PHP8对未过滤字符串的严格处理警告。
• 详细错误日志：方便定位PHP8环境下的具体问题，比如权限、MIME类型识别失败等。

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