Google Cloud Storage多分片断点续传curl请求异常排查

核心问题原因 #

你的问题大概率是三个关键错误导致：

• 分块大小不符合GCS要求
• 未指定curl读取文件的对应片段
• 未使用可恢复上传的会话URI

具体错误分析与修正 #

1. 分块大小不达标 #

GCS规定，可恢复上传中除最后一块外，每个分块必须至少5MiB（5242880字节）。你使用的256KB（262144字节）分块太小，GCS无法正确识别分块边界，会导致内容合并错误。

2. curl未正确读取文件片段 #

仅添加Content-Range头部是不够的，curl默认会上传整个文件。你需要加上--range <start>-<end>参数，让curl只读取并上传文件的对应区间，确保实际上传内容和Content-Range声明的范围一致。

3. 未使用会话URI #

GCS可恢复上传需要先初始化会话，获取专属的会话URI，后续所有分块上传都必须使用这个URI，而不是直接PUT到gs://bucket/object路径。直接上传会被当成独立请求，导致内容重复覆盖。

修正后的完整流程 #

步骤1：初始化可恢复上传会话 #

curl -X POST -H "Content-Length: 0" -H "x-goog-resumable: start" "gs://你的存储桶名/目标文件名"

执行后会返回一个Location响应头，复制这个值作为会话URI（比如https://storage.googleapis.com/upload/storage/v1/b/xxx/o?uploadType=resumable&upload_id=xxx）。

步骤2：上传分块（以10MiB文件为例） #

假设文件总大小为10485760字节，分两个5MiB块上传：

上传第一块（0-5242879字节）

curl -X PUT \
  -H "Content-Range: bytes 0-5242879/10485760" \
  --range 0-5242879 \
  --upload-file 你的本地文件名 \
  "刚才复制的会话URI"

上传第二块（5242880-10485759字节）

curl -X PUT \
  -H "Content-Range: bytes 5242880-10485759/10485760" \
  --range 5242880-10485759 \
  --upload-file 你的本地文件名 \
  "刚才复制的会话URI"

额外提示 #

如果上传中断，可发送HEAD请求到会话URI，获取已上传的范围：

curl -I "会话URI"

响应头中的Range字段会显示已上传区间，比如bytes=0-5242879，之后从下一个字节继续上传即可。

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