WordPress REST API：上传原始图片数据并解决媒体库空白问题

本教程详细阐述了如何通过wordpress rest api (v2) 上传原始图片数据，而非文件路径或url。针对常见上传后媒体库图片显示空白的问题，文章提供了基于curl的解决方案，核心在于将图片的二进制数据直接作为请求体发送，并正确设置`content-disposition`头部以指定文件名，确保图片在wordpress媒体库中正常显示和存储。

在开发过程中，我们经常会遇到需要将图片数据（例如从其他系统导出或经过处理的原始二进制数据，而非文件路径或URL）上传到WordPress媒体库的场景。然而，直接通过WordPress REST API (v2) 上传这类数据时，一个常见的问题是上传成功后，图片在WordPress后台的媒体库中显示为空白，无法正常预览或使用。这通常是由于对API请求体的构建方式理解有误导致的。

理解WordPress媒体上传API的要求

WordPress REST API的媒体上传端点（/wp/v2/media）设计用于接收文件的原始二进制内容作为HTTP请求体。许多开发者初次尝试时，可能会错误地将原始图片数据作为某个参数的值（例如source_url或data）通过form_params发送。然而，source_url参数是用于指定一个外部图片的URL，让WordPress从该URL下载图片；而form_params通常用于发送键值对形式的表单数据，不适合直接传输二进制文件流。

要正确上传原始图片数据，核心在于以下两点：

1. 将图片的原始二进制数据直接作为HTTP请求体发送。
2. 在HTTP请求头中正确设置Content-Disposition，以告知WordPress上传文件的原始文件名。

正确的上传方法：基于cURL的实现

以下是解决媒体库图片显示空白问题的详细步骤和示例代码，该方法通过将原始图片数据保存为临时文件，然后使用cURL将文件内容作为请求体直接上传。

MakeSong

AI音乐生成，生成高质量音乐，仅需30秒的时间

145

查看详情

步骤一：准备图片数据并保存为临时文件

如果你的图片数据是Base64编码的字符串，首先需要将其解码。为了确保数据以正确的二进制格式发送，一个稳健的方法是先将解码后的数据保存到一个临时文件中。这模拟了从文件系统读取文件进行上传的过程，并能更好地与API的期望匹配。

<?php
// 假设 $product['priority_web_image'] 包含图片信息
// $data 是 base64 编码的图片字符串
// $image_name 是包含扩展名的文件名，例如 "my_image.jpg"
if (isset($product['priority_web_image'])) {
    $image_name = $product['priority_web_image']['filename'];
    $base64_data = $product['priority_web_image']['data']; // 原始的 base64 编码数据

    // 1. 解码 base64 数据
    $decoded_data = base64_decode($base64_data);

    // 2. 生成一个唯一的临时文件路径
    // sys_get_temp_dir() 获取系统临时目录
    // uniqid() 生成唯一ID，防止文件名冲突
    $filepath = sys_get_temp_dir() . '/' . uniqid() . '_' . $image_name;

    // 3. 将解码后的数据写入临时文件
    file_put_contents($filepath, $decoded_data);

    // 确保文件已成功创建
    if (!file_exists($filepath)) {
        echo "错误：无法创建临时图片文件。\n";
        return; // 或者抛出异常
    }

    // ... 后续的 cURL 上传代码将在这里 ...
}
?>

步骤二：构建并执行cURL请求

有了临时文件后，我们可以使用cURL来构建HTTP POST请求。关键在于设置CURLOPT_POSTFIELDS为文件的原始内容，并在CURLOPT_HTTPHEADER中包含Content-Disposition。

<?php
// 假设 $url 是 WordPress 站点的根 URL，例如 "https://yourdomain.com"
// 假设 $result_auth->access_token 是你的 Bearer 认证令牌

    // 4. 读取临时文件的内容作为请求体
    $file_content = file_get_contents($filepath);
    $filename_for_upload = $image_name; // 使用原始文件名作为上传文件名

    // 5. 初始化 cURL 请求
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 设置为 true，将响应作为字符串返回
    curl_setopt($ch, CURLOPT_URL, $url . '/wp-json/wp/v2/media/'); // WordPress 媒体上传 API 端点
    curl_setopt($ch, CURLOPT_POST, 1); // 设置为 POST 请求
    curl_setopt($ch, CURLOPT_POSTFIELDS, $file_content); // 将文件内容直接作为请求体

    // 6. 设置 HTTP 请求头
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        // 关键：Content-Disposition 头，告知 WordPress 文件名
        "Content-Disposition: attachment; filename=\"$filename_for_upload\"",
        // 认证头，使用你的 Bearer 令牌
        'Authorization: Bearer ' . $result_auth->access_token,
        // 可选：Content-Type 头。WordPress通常能从文件名推断MIME类型，
        // 但如果遇到问题，可以明确设置，例如 'Content-Type: image/jpeg'
    ]);

    // 7. 执行 cURL 请求
    $result = curl_exec($ch);

    // 8. 关闭 cURL 句柄
    curl_close($ch);

    // 9. 解码 API 响应
    $api_response = json_decode($result, true);

    // 10. 清理临时文件
    unlink($filepath);

    // 打印或处理 API 响应
    print_r($api_response);

    return $api_response;
}
?>

注意事项与最佳实践

1. 临时文件管理： 在上传成功或失败后，务必使用unlink($filepath)删除创建的临时文件，以避免服务器磁盘空间被不必要的文件占用。
2. Content-Disposition头： 这是解决媒体库空白问题的关键。它告诉WordPress正在上传的文件名，WordPress会根据这个文件名来处理和存储图片。请确保filename值包含正确的文件扩展名（如.jpg, .png等）。
3. 错误处理： 在实际应用中，应该对file_put_contents、file_exists、curl_exec以及API响应进行严格的错误检查。例如，检查curl_exec的返回值，使用curl_errno()和curl_error()获取cURL错误信息，并检查$api_response中是否存在code或message字段指示的API错误。
4. 认证： 示例中使用了Bearer令牌进行认证。请确保你的WordPress站点已配置JWT认证或其他OAuth认证插件，并且你的令牌是有效的。
5. MIME类型： 尽管在上述解决方案中未明确设置Content-Type头，WordPress通常能够根据Content-Disposition头中提供的文件名来推断文件的MIME类型。如果遇到特定图片类型上传失败的问题，可以尝试在CURLOPT_HTTPHEADER中添加'Content-Type: image/jpeg'或'Content-Type: image/png'等相应的MIME类型。
6. Guzzle HTTP客户端： 如果你使用的是Guzzle等HTTP客户端库，发送原始二进制数据的方法略有不同。你应该使用body选项直接传递文件内容，而不是form_params。

   // Guzzle 客户端发送原始二进制数据的概念示例
   // $client = new GuzzleHttp\Client();
   // $response = $client->request('POST', $url . '/wp-json/wp/v2/media/', [
   //     'headers' => [
   //         'Authorization' => 'Bearer ' . $result_auth->access_token,
   //         'Content-Disposition' => 'attachment; filename="' . $filename_for_upload . '"',
   //         // 'Content-Type' => 'image/jpeg', // 可选
   //     ],
   //     'body' => $file_content, // 直接将文件内容作为请求体
   // ]);
   // $api_response = json_decode($response->getBody(), true);

   登录后复制

总结

通过WordPress REST API上传原始图片数据时，关键在于理解API期望的是文件的原始二进制内容作为请求体，并通过Content-Disposition头提供文件名。将Base64编码的图片数据解码并暂时保存到文件中，然后使用cURL（或Guzzle等HTTP客户端的等效方法）将文件内容直接作为HTTP请求体发送，并配合正确的Content-Disposition头，就能成功将图片上传到WordPress媒体库，并确保其正常显示。遵循这些步骤和注意事项，将有效解决媒体库图片显示空白的问题，实现高效、可靠的图片上传流程。

以上就是WordPress REST API：上传原始图片数据并解决媒体库空白问题的详细内容，更多请关注php中文网其它相关文章！