本教程详细阐述了如何通过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通常用于发送键值对形式的表单数据，不适合直接传输二进制文件流。
要正确上传原始图片数据，核心在于以下两点：
- 将图片的原始二进制数据直接作为HTTP请求体发送。
- 在HTTP请求头中正确设置Content-Disposition，以告知WordPress上传文件的原始文件名。
正确的上传方法：基于cURL的实现
以下是解决媒体库图片显示空白问题的详细步骤和示例代码，该方法通过将原始图片数据保存为临时文件，然后使用cURL将文件内容作为请求体直接上传。
步骤一：准备图片数据并保存为临时文件
如果你的图片数据是Base64编码的字符串，首先需要将其解码。为了确保数据以正确的二进制格式发送，一个稳健的方法是先将解码后的数据保存到一个临时文件中。这模拟了从文件系统读取文件进行上传的过程，并能更好地与API的期望匹配。
步骤二：构建并执行cURL请求
有了临时文件后，我们可以使用cURL来构建HTTP POST请求。关键在于设置CURLOPT_POSTFIELDS为文件的原始内容，并在CURLOPT_HTTPHEADER中包含Content-Disposition。
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;
}
?>注意事项与最佳实践
- 临时文件管理： 在上传成功或失败后，务必使用unlink($filepath)删除创建的临时文件，以避免服务器磁盘空间被不必要的文件占用。
- Content-Disposition头： 这是解决媒体库空白问题的关键。它告诉WordPress正在上传的文件名，WordPress会根据这个文件名来处理和存储图片。请确保filename值包含正确的文件扩展名（如.jpg, .png等）。
- 错误处理： 在实际应用中，应该对file_put_contents、file_exists、curl_exec以及API响应进行严格的错误检查。例如，检查curl_exec的返回值，使用curl_errno()和curl_error()获取cURL错误信息，并检查$api_response中是否存在code或message字段指示的API错误。
- 认证： 示例中使用了Bearer令牌进行认证。请确保你的WordPress站点已配置JWT认证或其他OAuth认证插件，并且你的令牌是有效的。
- MIME类型： 尽管在上述解决方案中未明确设置Content-Type头，WordPress通常能够根据Content-Disposition头中提供的文件名来推断文件的MIME类型。如果遇到特定图片类型上传失败的问题，可以尝试在CURLOPT_HTTPHEADER中添加'Content-Type: image/jpeg'或'Content-Type: image/png'等相应的MIME类型。
-
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媒体库，并确保其正常显示。遵循这些步骤和注意事项，将有效解决媒体库图片显示空白的问题，实现高效、可靠的图片上传流程。
