前端UI组件后端【免费下载链接】uppyThe next open source file uploader for web browsers :dog:项目地址https://gitcode.com/gh_mirrors/up/uppy点击查看免费下载本指南以uppy/aws-s3插件的 CHANGELOG.md 为核心骨架结合仓库源码index.ts、S3Uploader.ts、s3-client深入讲解Uppy S3 插件在 v6 中的一次性重写如何将配置收敛为三种互斥签名模式signRequest新增的key覆盖与headers返回能力解决了哪些真实问题以及这些能力在源码层面是如何实现的。读完本文你将掌握uppy/aws-s3从接入、选型、配置到故障排查的完整链路并能在自己的项目中直接复刻三种签名模式的最小可用配置。一、为什么 v6 值得一次从零重写从 changelog 看架构演进uppy/aws-s3的 CHANGELOG.md 中最核心的里程碑是6.0.0插件被从零重写对应上游 PR #6345其核心变化可以概括为三句话插件构建在一个独立的 S3 客户端之上不再依赖散落的数十个回调选项配置被收敛为三种互斥的签名模式getCredentials、signRequest、companionEndpoint任何 S3 兼容服务如 R2、MinIO、DigitalOcean Spaces在每种签名模式下都能工作——包括客户端签名此前客户端签名硬编码了*.amazonaws.com只能面向 AWS 本体。这一重写带来了清晰的选项迁移清单对升级用户至关重要移除的选项endpoint、headers、cookiesRule、getTemporarySecurityCredentials、getUploadParameters、signPart、createMultipartUpload、listParts、abortMultipartUpload、completeMultipartUpload、uploadPartBytes、retryDelays。新增的选项s3Endpoint、region、getCredentials、signRequest、companionEndpoint、generateObjectKey。不变的选项shouldUseMultipart、getChunkSize、allowedMetaFields、limit。从源码看这种少即是多的设计直接体现在插件初始化逻辑中。在 index.ts 的#initS3Client()里插件按照companionEndpoint→getCredentials→signRequest的优先级分支分别实例化两种底层客户端companionEndpoint模式 →S3CompanionCompanionS3.ts通过与 Companion 服务端交互完成签名与上传getCredentials与signRequest模式 →S3miniS3mini.ts一个浏览器端可用的 S3 兼容客户端源自 good-lly/s3miniMIT 许可Uppy 做了适配改造。如果三种选项一个都没传插件会直接抛出TypeErrorOne of options companionEndpoint, signRequest, or getCredentials is required。这种互斥但必选其一的类型设计在 index.ts 中用 TypeScript 联合类型表达让配置错误在编译期/实例化期就能暴露而不是等到上传时才发现签名方式缺失。二、三种签名模式逐一拆解1.getCredentials客户端 SigV4 签名临时凭证这是完全自给自足的模式不需要 Companion也不需要自己的签名服务端只要提供一个能返回临时安全凭证的函数即可。插件使用 SigV4 在浏览器端直接对请求签名。配置要点见 index.tss3Endpoint必填 stringS3 兼容服务的端点例如https://s3.us-east-1.amazonaws.com/my-bucket或https://play.min.io/my-bucketregion可选 stringAWS 区域缺省时回退到getCredentials响应中的 region再不行用auto见 S3mini.tsgetCredentials必填函数返回{ credentials: { accessKeyId, secretAccessKey, sessionToken, expiration? }, region }通常由你的后端调用 STSSecurity Token Service换取。凭证的获取与缓存逻辑在 S3mini.ts 的_getCachedCredentials()中实现凭证会被缓存复用并且缓存的是Promise 本身保证并发签名请求共享同一次凭证拉取请求结束后清空 Promise 缓存允许下次重新获取。更关键的是过期自动续期当 S3 返回ExpiredToken或InvalidAccessKeyId错误码时客户端会清空凭证缓存并用新凭证重试一次见 S3mini.ts避免临时凭证在长传过程中过期导致上传失败。最小可用示例import Uppy from uppy/core import AwsS3 from uppy/aws-s3 const uppy new Uppy() uppy.use(AwsS3, { s3Endpoint: https://s3.us-east-1.amazonaws.com/my-bucket, region: us-east-1, getCredentials: async () { const resp await fetch(/api/s3/credentials) // 后端用 STS 签发 return resp.json() // { credentials, region } }, })2.signRequest自带签名器客户端或服务端皆可当你的后端已有签名能力比如用 AWS SDK 的预签名器或自定义签名算法时用signRequest模式最灵活。它不要求s3Endpoint只要求一个签名函数uppy.use(AwsS3, { signRequest: async ({ method, key, uploadId, partNumber }) { const resp await fetch(/api/s3/sign, { method: POST, body: JSON.stringify({ method, key, uploadId, partNumber }), }) return resp.json() // { url } 或 { url, key } 或 { url, headers } }, })签名函数的输入输出类型定义在 types.ts输入是PresignableRequest联合类型覆盖了 S3 的全部操作PUT单文件上传、POST创建分片上传 / 完成分片、GET列出已传分片、DELETE删除对象 / 中止分片上传带uploadId/partNumber的分片操作会附带对应参数输出是PresignedResponseurl必填key?可选的对象键覆盖headers?可选的随请求发送的签名头。signRequest会被调用多次创建上传、传每个分片、完成上传……因此适合把签名逻辑完全放在服务端、客户端不持有任何密钥的架构。这是不带 Companion、用自己的后端签名的主流方案。3.companionEndpointCompanion 签名延续经典用法如果你已经在跑 Uppy Companion 服务端这是零改动接入的方式也支持远程文件网盘等 Provider 文件的服务端转发上传uppy.use(AwsS3, { limit: 2, timeout: 1000 * 60, // 1 分钟 companionEndpoint: https://companion.myapp.com/, })从 CompanionS3.ts 可以看到该模式下的客户端会与 Companion 的/s3/*系列端点交互POST /s3/params获取单文件 PUT 上传的预签名 URL 与表单字段{ url, fields }随后以 multipart/form-data 提交文件POST /s3/multipart创建分片上传返回{ key, uploadId }GET /s3/multipart/{uploadId}/{partNumber}获取上传分片的预签名 URLPOST /s3/multipart/{uploadId}/complete完成分片上传GET /s3/multipart/{uploadId}列出已上传分片断点续传用DELETE /s3/multipart/{uploadId}中止分片上传。值得注意的是 Companion 模式下对象键由服务端生成在 index.ts 的#generateKey()中若处于companionEndpoint模式直接返回file.name最终键由 Companion 决定此时传入的generateObjectKey选项会被忽略。三、v6.1.0 新能力signRequest返回{ url, key }的对象键覆盖这是 changelog 6.1.0 引入的一个重要语义修正对应 issue #6496。在此之前当签名服务端把对象存在与 Uppy 提议不同的键下比如加了一个目录前缀、或使用服务端生成的随机文件名时upload-success事件报告的仍是客户端生成的旧键前后不一致。6.1.0 的行为在创建上传的单文件PUT、分片创建请求中签名器返回{ url, key }Uppy 就会在后续整个上传流程中使用这个key并在upload-success事件中如实上报它。需要特别注意的两个边界changelog 原文明确说明key是可选的——只返回{ url }的签名器行为与以前完全一致携带uploadId的请求如分片上传、列分片、完成上传必须按收到的key来签名这些请求返回的key会被忽略因为键在创建阶段已经确定。源码佐证在 S3mini.ts 的request()中签名完成后会计算resolvedKey// A blank key from the signer is not an override. const resolvedKey signerKey?.trim() ? signerKey : requestedKey这个resolvedKey会一路穿透到putObject的返回值在分片场景中S3Uploader.ts 创建分片上传后把resolvedKey保存为#resolvedKey后续所有分片上传、完成请求都使用它最终随UploadResult{ location, key, uploadId? }上报。6.2.0 的补充修正空白key不算覆盖6.2.0 进一步收紧了语义如果签名器返回的key是空白字符串如或 则视为没有覆盖仍然使用 Uppy 请求的键。这正是上面源码中signerKey?.trim()判断的作用——trim()后为空则回退到requestedKey。这防止了签名器在未实现 key 返回时误传空值导致的键丢失。四、v6.2.0 新能力signRequest返回headers携带签名头6.2.0 的另一项 Minor ChangesignRequest可以返回headers随预签名请求一并发送——典型用途是发送签名过的Content-Disposition控制下载时的文件名。从 types.ts 的注释可以提炼出三条硬性约束接入时必须遵守必须也在桶的 CORSAllowedHeaders中声明这些头部参与了 SigV4 签名属于X-Amz-SignedHeaders浏览器跨域请求若未在 CORS 白名单中会直接失败Content-Type特殊若headers里带了Content-Type它会替换插件内置的 Content-Type文件自身的 MIME 类型禁止浏览器禁用头Host、Content-Length、Date等浏览器无法由 JS 设置的头部绝不能出现在headers中。请求侧的合并逻辑在 S3Client.ts 的xhr()中先放内置Content-Type再铺开签名器的headers后者的Content-Type会覆盖前者fetcher会折叠仅大小写不同的同名头因此小写content-type同样生效。uppy.use(AwsS3, { signRequest: async ({ method, key, uploadId, partNumber }) { const resp await fetch(/api/s3/sign, { method: POST, body: JSON.stringify({ method, key, uploadId, partNumber }), }) return resp.json() // 可返回形如 // { url, key, headers: { Content-Disposition: attachment; filenamereport.pdf } } }, })五、默认值、分块与并发控制从源码看参数语义在 v6 中未在 changelog 变更列表里的四个不变选项承担了上传策略的配置职责它们的默认值定义在 index.ts选项默认值语义shouldUseMultipart文件大小 100MB 时使用分片也可传true总是分片/false总是单 PUT/ 函数按文件判定limit6并发上传文件数上限6 对应浏览器 HTTP/1.1 每域 6 条连接的并发上限避免在浏览器层排队allowedMetaFieldstrue允许作为 S3 元数据上传的字段传null/false或数组可精确控制getChunkSize见下自定义分片大小函数分片相关的两个硬性常量在 S3Uploader.tsMIN_CHUNK_SIZE 5MBS3 对除最后一片外的分片有 5 MiB 最小限制因此小于 5MB 的文件自然退化为单片上传MAX_PARTS 10000S3 允许的最大分片数。默认分片大小按Math.ceil(fileSize / MAX_PARTS)计算保证不超上限若自定义getChunkSize导致分片数超限会自动放大分片到刚好不超过 10000 片。generateObjectKey默认crypto.randomUUID()-文件名只在非 Companion 模式下生效见上文第三节末尾。这些默认值共同决定了上传的外形大文件自动走分片、小文件走单 PUT并发受limit控制元数据受allowedMetaFields过滤见 index.ts。六、上传主流程与可靠性机制单 PUT / 分片 / 断点续传单文件 PUT 与分片上传的完整链路S3Uploader.ts 是每个文件上传状态的载体。start()根据shouldUseMultipart分流单 PUTL253-L270putObject一次完成返回location与key分片上传L272-L351createMultipartUpload→ 逐片uploadPart每片完成后触发s3-multipart:part-uploaded事件载荷为{ PartNumber, ETag }→completeMultipartUpload发送CompleteMultipartUploadXML包含每片的 PartNumber/ETag→ 上报{ location, key, uploadId }。成功时插件触发upload-successbody 为{ location, key }见 index.tsAwsBody类型即{ location, key }。断点续传与 Golden Retriever 集成分片创建后插件会把{ uploadId, key }持久化到文件状态file.s3MultipartS3Uploader.ts。Golden Retriever 插件会在页面刷新后恢复该状态恢复时 resume 逻辑 先listParts查询 S3 上已上传的分片把已完成的 ETag 同步回本地再只补传缺失分片。上传成功后会清空s3Multipart状态。网络容错与重试底层请求统一走 S3Client.ts 的fetcher自动重试 3 次重试策略为5xx 服务端错误与 429 限流会重试4xx 客户端错误除 429不重试L102-L116离线自动挂起waitForOnline()检测到navigator.onLine false时挂起请求待online事件触发后自动续传L25-L65并配合 AbortSignal 支持取消上传失败不中止 S3 分片S3Uploader.ts 的#onError刻意不在 S3 侧 abort以便用户重试时从断点续传只有用户主动取消abort()默认abortInS3: true才会调用abortMultipartUpload清理 S3 上的孤儿分片。若想保留分片以便手动清理或稍后恢复可传{ abortInS3: false }。远程文件上传对于来自 Provider如 Google Drive的远程文件index.ts 通过uploadRemoteFile走 Companion 的服务端 S3 上传通道body 中标记protocol: s3-multipart上传期间会临时关闭resumableUploads能力标识远程上传不支持浏览器端暂停恢复。七、事件、元数据与迁移检查清单事件一览upload-progress{ uploadStarted, bytesUploaded, bytesTotal }s3-multipart:part-uploaded(file, { PartNumber, ETag })upload-success{ status: 200, body: { location, key }, uploadURL: location }upload-error/upload-start/file-removed标准 Uppy 语义。从 v5 迁移到 v6 的检查清单对照上文移除的选项列表删除endpoint、getUploadParameters、signPart等旧回调改为三种签名模式之一原先使用getTemporarySecurityCredentials的改用getCredentialss3Endpoint原先用headers选项统一附加请求头的改为在signRequest返回值中提供headers并同步在桶的 CORS 中放行验证签名服务端是否返回{ url, key }若返回确保键语义一致若返回空白 key插件会回退到请求键6.2.0分片相关能力createMultipartUpload/listParts等自定义回调已内置于独立的 S3 客户端无需再自行实现。八、测试与验证仓库如何保障三种模式uppy/aws-s3的测试同样围绕三种模式 兼容服务展开可作自查参考index.test.ts插件级集成测试覆盖签名模式初始化、事件发射、元数据过滤等minio.test.ts compose.minio.yaml用 Docker 起一个 MinIO 实例对真实 S3 兼容服务跑客户端层测试单 PUT、分片、列分片、完成/中止、断点续传这正是 changelog 强调任何 S3 兼容服务可用的落地验证test-utils/browser-crypto.ts为测试环境提供crypto.randomUUID等浏览器 API 垫片。如果你打算在本地验证接入可以参照仓库的测试思路用docker compose -f packages/uppy/aws-s3/test/s3-client/compose.minio.yaml up起 MinIO再把s3Endpoint指向它、用getCredentials返回 MinIO 的临时凭证即可在非 AWS 环境下完整跑通三种签名模式。总结uppy/aws-s3v6 的重写本质上是把签名方式从十几个零散回调中提炼为三种互斥模式同时让浏览器端拥有了一个独立的 S3 兼容客户端。{ url, key }的对象键覆盖修复了服务端改名但客户端上报旧键的语义漏洞headers返回则解锁了Content-Disposition等签名头的场景。配合默认 100MB 分片阈值、limit: 6并发、5MB 最小分片与 10000 片上限、自动重试/离线续传/断点恢复等机制这一插件可以作为几乎所有 S3 兼容对象存储的前端上传方案。更多细节可继续查阅仓库中的 README.md 与 源码目录。赞分享前端UI组件后端【免费下载链接】uppyThe next open source file uploader for web browsers :dog:项目地址https://gitcode.com/gh_mirrors/up/uppy点击查看免费下载相关推荐Uppy AWS S3 PHP 示例基于预签名 URL 的 PHP 服务端签名上传方案Uppy AWS S3 PHP 示例基于预签名 URL 的 PHP 服务端签名上传方案 导读 本文围绕仓库 examples/aws php https:前端UI组件后端N_m3u8DL-RE 源码编译3 条命令拿到任意平台的可执行文件N_m3u8DL RE 源码编译3 条命令拿到任意平台的可执行文件 N_m3u8DL RE 源码编译就是为这个场景准备的官方 Release 版本落后于代码CLI音视频Hive AWS S3 Tool 深度指南基于 SigV4 签名的对象存储 MCP 工具集Hive AWS S3 Tool 深度指南基于 SigV4 签名的对象存储 MCP 工具集 本文以 HiveMulti Agent Harness for人工智能AI Agent多智能体MCP 服务工具调用浏览器控制上一篇Seraphine 安装教程10 分钟跑通英雄联盟战绩查询工具下一篇chromaticBetterNCM 重写版Chromium/V8 注入修改器安装与上手教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)