使用GCS签名URL上传文件触发Metadata part is too large错误如何解决

• 你使用POST方法生成GCS V4版本签名URL，该类URL默认适配表单上传场景，未配置上传策略时默认最大仅支持2MB文件上传，刚好匹配你遇到的阈值。
• 报错Metadata part is too large是因为超限制的请求体被GCS误识别为metadata部分，触发了表单上传的元数据大小限制。

方案1：保留POST表单上传模式 #

生成签名URL时添加policy配置，明确允许的文件大小范围，示例代码如下：

import datetime
from google.cloud.storage.blob import Blob

blob = Blob.from_string(filepath, client=gcp_storage_client)
# 配置上传策略，可按需调整文件大小上限，以下示例为10GB
policy = {
    "expiration": (datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=5)).isoformat(),
    "conditions": [
        ["content-length-range", 0, 10 * 1024 * 1024 * 1024]
    ]
}
signed_url = blob.generate_signed_url(
    version="v4",
    expiration=datetime.timedelta(minutes=5),
    method="POST",
    policy=policy
)

方案2（更推荐）：改用PUT方法生成签名URL #

非表单上传场景直接将请求方法改为PUT即可解除2MB限制，最大支持5TB单文件上传，调整后代码如下：

from google.cloud.storage.blob import Blob
import datetime

blob = Blob.from_string(filepath, client=gcp_storage_client)
signed_url = blob.generate_signed_url(
    version="v4",
    expiration=datetime.timedelta(minutes=5),
    method="PUT"
)

注意：使用PUT方式上传时，客户端无需构造表单请求，直接将文件二进制内容放入请求体即可，请求头Content-Type需要和生成签名URL时指定的参数保持一致，生成时未指定则上传时不要携带该头字段。

如果需要上传10GB以上的超大文件，建议搭配分片上传能力使用，提升上传稳定性。

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