通过wp api上传媒体库图片成功但图片损坏、尺寸过小的解决方案

这类问题的核心矛盾是：上传接口返回了成功状态码，但服务端实际落盘的文件并非完整的有效图片，和WP媒体库本身的存储逻辑关联很小，基本是请求构造、传输链路、环境配置三类问题导致的，可按以下顺序逐一排查：

• 请求Content-Type设置不匹配
  很多调用方上传时没有将请求头的Content-Type设置为和图片本身一致的MIME类型，反而用了表单、JSON接口常用的默认值，WP收到请求后不会将请求体识别为图片二进制，只会按对应MIME的解析规则截断、存储内容，最终生成的文件是不完整的解析结果，自然出现损坏、尺寸远小于原图的问题。正确的设置是上传jpeg图时设为image/jpeg，png图设为image/png，不要强制使用multipart/form-data格式传输原生二进制流。
• 客户端对二进制流做了二次编码转换
  多数HTTP客户端默认会自动转换请求体格式，如果调用时没有将读取到的图片原始字节作为请求体，反而把二进制内容做了UTF-8等字符串编码转换，会直接篡改图片的二进制结构。WP将篡改后的内容落盘后，生成的文件本质是乱码文本，不仅无法正常打开，文件大小也会因为编码转换的字节变化和原图存在明显差异。传输时需要注意：直接将文件以rb模式读取的原始字节作为请求体传入，禁用HTTP客户端的自动请求体转换逻辑，不要对二进制内容做任何字符串层面的处理。
• 反向代理链路截断请求内容
  如果站点前置了Nginx、CDN、云网关等代理层，默认配置的最大请求体大小如果小于待上传的图片尺寸，代理会直接截断传输的请求内容，但不会触发WP的接口报错逻辑。截断后的残片会被直接传给上传接口，WP完成落盘后依旧会返回上传成功的响应，最终媒体库存的就是残缺的图片片段。这种情况需要调整代理层的请求体大小限制，确保允许传输的最大文件尺寸大于待上传的图片，同时关闭代理层对二进制请求的自动压缩、修改逻辑。
• 服务器图片处理环境缺失
  当服务器缺少GD库、Imagick等PHP图片处理扩展时，WP在收到完整图片后，执行缩略图生成、图片压缩的环节可能出现静默失败，导致主图片文件没有完成完整写入就提前返回成功。这类情况可以临时关闭WP的自动图片压缩、多尺寸缩略图生成逻辑，再重新上传测试，如果上传后图片恢复正常，就需要补全对应的PHP图片处理扩展。

快速定位技巧：下载上传成功后生成的媒体文件，用十六进制编辑器查看文件头：正常jpeg文件头为FF D8 FF，png文件头为89 50 4E 47，如果文件头不符合对应格式，即可确定是传输过程中二进制被篡改、截断导致的问题，不是媒体库本身的存储bug。

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