You need to enable JavaScript to run this app. Uppy结合Laravel/Vue实现大文件分片上传 调用AWS S3接口报InvalidPart错误
优惠活动
大模型
产品
解决方案
定价
更多

Uppy结合Laravel/Vue实现大文件分片上传 调用AWS S3接口报InvalidPart错误

S3分片上传配置异常问题排查

问题描述

正在使用Uppy的Vue组件实现大文件上传功能,目前遇到运行障碍。
参考社区成熟方案将Uppy实例中的companionUrl配置为指向自有服务端地址,同时编写对应的路由与处理函数响应上传请求,除调用AWS的completeMultipartUpload接口环节外,其余流程均可正常运行。

执行合并分片的代码如下:

$result = $client->completeMultipartUpload([
    'Bucket'          => 'bucket-name',
    'Key'             => $key,
    'UploadId'        => $uploadId,
    'MultipartUpload' => [
        'Parts' => $formattedParts,
    ],
]);

调用上述接口时返回400 Bad Request错误:

Error executing "CompleteMultipartUpload" on "https://bucket-name.s3.amazonaws.com/NewProject.png?uploadId=nlWLdbNgB9zgarpLBXnj17eOIGAmQM_xyBArymtwdM71fhbFvveggDmL6fz4blz.B95TLhMatDvodbMb5p2ZMKqdlLeLFoSW1qcu33aRQTlt6NbiP_dkDO90DFO.pWGH"; AWS HTTP error: Client error: `POST https://bucket-name.s3.amazonaws.com/NewProject.png?uploadId=nlWLdbNgB9zgarpLBXnj17eOIGAmQM_xyBArymtwdM71fhbFvveggDmL6fz4blz.B95TLhMatDvodbMb5p2ZMKqdlLeLFoSW1qcu33aRQTlt6NbiP_dkDO90DFO.pWGH` resulted in a `400 Bad Request` response:
<Error><Code>InvalidPart</Code><Message>One or more of the specified parts could not be found.  The part may not have be (truncated...)
InvalidPart (client): One or more of the specified parts could not be found.  The part may not have been uploaded, or the specified entity tag may not match the part's entity tag. - <Error><Code>InvalidPart</Code><Message>One or more of the specified parts could not be found.  The part may not have been uploaded, or the specified entity tag may not match the part's en

排查后定位到问题根源:将官方Companion的JavaScript逻辑翻译为PHP实现时,虽然能正常返回URL,但生成的地址不符合分片上传要求——最明显的差异是,生成预签名链接时没有传入UploadId与PartNumber参数。
查阅AWS官方文档、技术社区公开资料后,未找到与官方JS版getSignedUrl方法等价的PHP实现方案,当前的分片签名接口代码如下:

public function signPartUpload(Request $request, $uploadId, $partNumber)
{
    $client = new S3Client([
        'version' => 'latest',
        'region'  => 'us-east-1',
    ]);

    $key = $request->has('key') ? $request->get('key') : null;

    if (!is_string($key)) {
        return response()->json(['error' => 's3: the object key must be passed as a query parameter. For example: "?key=abc.jpg"'], 400);
    }

    if (!intval($partNumber)) {
        return response()->json(['error' => 's3: the part number must be a number between 1 and 10000.'], 400);
    }

    //Creating a presigned URL
    $cmd = $client->getCommand('PutObject', [
        'Bucket' => 'bucket-name',
        'Key' => $key
    ]);

    $response = $client->createPresignedRequest($cmd, '+20 minutes');
    $presignedUrl = (string)$response->getUri();

    return response()->json(['url' => $presignedUrl]);
}

解决方案

  • 核心问题修正:分片上传场景下的预签名URL,不能直接调用PutObject生成普通对象上传的签名,必须在生成命令时补充分片上传必需的两个参数:UploadId、PartNumber。
    AWS S3 PHP SDK中,分片上传的预签名生成逻辑和普通上传的差异仅为命令参数,修正后的签名代码如下:
    public function signPartUpload(Request $request, $uploadId, $partNumber)
    {
        $client = new S3Client([
            'version' => 'latest',
            'region'  => 'us-east-1',
        ]);
    
        $key = $request->has('key') ? $request->get('key') : null;
    
        if (!is_string($key)) {
            return response()->json(['error' => 's3: the object key must be passed as a query parameter. For example: "?key=abc.jpg"'], 400);
        }
    
        $partNumber = (int)$partNumber;
        if (!$partNumber || $partNumber < 1 || $partNumber > 10000) {
            return response()->json(['error' => 's3: the part number must be a number between 1 and 10000.'], 400);
        }
    
        // 生成预签名时补充分片上传必需的UploadId、PartNumber参数
        $cmd = $client->getCommand('PutObject', [
            'Bucket'     => 'bucket-name',
            'Key'        => $key,
            'UploadId'   => $uploadId,
            'PartNumber' => $partNumber,
        ]);
    
        $response = $client->createPresignedRequest($cmd, '+20 minutes');
        $presignedUrl = (string)$response->getUri();
    
        return response()->json(['url' => $presignedUrl]);
    }
    
  • 校验上传分片的ETag一致性:修正签名逻辑后,前端使用预签名URL上传分片时,服务端在收集分片信息用于completeMultipartUpload时,必须从S3返回的响应头中提取每个分片对应的ETag值,和分片序号一并存入$formattedParts数组,保证分片参数和实际上传的分片完全匹配,避免再次出现InvalidPart错误。
  • 预签名URL生效逻辑校验:生成的预签名URL需要满足S3的分片上传请求规则:前端发起PUT请求上传分片时,请求路径必须和签名时的路径完全一致,不能随意修改请求的query参数,否则签名校验会直接失败。

内容的提问来源于stack exchange,提问作者Josh

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.24 14:15:01