GCS通过签名URL下载文件被附加元数据头尾致损坏如何解决

GCS默认不会对上传的对象内容做任何篡改，你观察到的文件首尾附加元数据、图片损坏问题，本质是上传环节请求格式错误，导致HTTP请求的分段边界标记被当成文件内容存入了存储桶，和下载逻辑、GCS侧的内容修改配置无关。
这类问题90%以上的触发原因是：使用签名URL上传时，错误地将multipart/form-data格式的完整请求体（包含multipart分段的头、尾边界字符串、表单字段描述信息）直接作为文件内容发送，GCS不会自动解析PUT请求里的multipart结构，会把收到的所有请求体字节原封不动存为对象内容，下载时自然会带出这些多余内容。

• 第一步先确认问题边界：在GCS控制台找到出问题的对象，直接用控制台自带的下载功能拉取到本地，如果文件仍然带多余的头尾内容，可100%确认问题出在上传环节，和下载签名URL的配置无关。
• 修正上传请求逻辑：
  • 使用PUT类型的签名URL做文件直传时，禁止将文件包装在FormData对象中发送，直接将文件的原始二进制流作为PUT请求的唯一请求体即可。
  • 上传请求头中的Content-Type值，必须和生成签名URL时指定的MIME类型完全一致，不能留空、也不能填multipart/form-data。
  • 参考正确的前端上传实现：

    /**
     * @param {string} signedUrl 后端生成的GCS签名URL
     * @param {Blob} file 待上传的文件对象
     */
    async function uploadToGCS(signedUrl, file) {
      await fetch(signedUrl, {
        method: 'PUT',
        headers: {
          // 必须和生成签名URL时传入的Content-Type参数完全匹配
          'Content-Type': file.type
        },
        // 直接传文件原始二进制，不要包装FormData
        body: file
      })
    }
    

• 特殊场景处理：如果你需要在上传时附带自定义对象元数据，不要通过multipart表单传字段，要么在生成签名URL时就把元数据绑定到签名参数里，要么改用GCS XML API规范的POST签名URL构造表单上传请求，不能直接把普通web表单的FormData请求体发给PUT类型的签名URL。
• 配置校验：生成签名URL时，不要随意设置Content-Encoding头，比如上传未压缩的原文件时不要指定gzip等编码值，否则下载时自动解压逻辑会导致内容错乱。

修复上传逻辑后，新上传的文件满足两个条件即可确认配置正确：

• 从GCS控制台直接下载的文件可以正常打开，无多余头尾内容
• 本地原文件的MD5值，和通过签名URL下载的文件MD5值完全一致

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