前端后端移动开发【免费下载链接】amplify-jsA declarative JavaScript library for application development using cloud services.项目地址https://gitcode.com/gh_mirrors/am/amplify-js点击查看免费下载本文以aws-amplify/storage包的 CHANGELOG.md 为骨架结合 packages/storage 目录下的源码实现系统梳理 Amplify JavaScript Storage 从 v0.1.1 到 v6.17.0 的核心演进脉络。读完你将掌握v6 时代path优先 API 的设计动机、uploadData/downloadData/getUrl/list等核心方法的能力边界与参数细节、多部分上传的底层行为、SSR 服务端上传的使用方式以及版本升级时需要关注的兼容性要点。一、版本演进总览从 0.x 到 6.17.0 的三次架构跃迁aws-amplify/storage的变更历史横跨 2018 年至 2026 年可以从时间线上划分出几个明显的发展阶段阶段版本区间关键主题早期成型0.1.1 – 3.x2018–2020基于 AWS SDK v3 客户端、SSE、ACL、上传进度、多部分上传、本地测试端点v4/v5 过渡4.x – 5.x2020–2023分页、copy API、getProperties API、自定义 S3 client 与 DOM 级 XML 解析、用户代理user agent增强v6 现代化6.0.x – 6.17.02023–2026path优先 API、accessLevel/key弃用、服务端SSRuploadData、预签名 PUT URL、显式 AmplifyContext从源码角度看当前版本6.17.0的 package.json 声明了aws-amplify/core的 peer 依赖为^6.19.0与 CHANGELOG 中“6.17.0 提高 peer 最低版本以防范版本错配安装”的说明完全吻合。包内同时维护了mainCJS、moduleESM、react-native、browser四套入口并暴露了.,./internals,./server,./s3,./s3/server五个子路径导出这与 CHANGELOG 中反复出现的“服务端能力”“内部测试入口”“tree-shaking 优化”等条目一一对应。二、v6 的核心转向path优先 API 与key/accessLevel弃用2.1 为什么引入path6.4.02024-04-29是 v6 演化中最重要的里程碑之一一次引入了五项与path相关的功能uploadData增加path参数支持#13099listAPI 同时接受prefix与path#13100copyAPI 增加path支持#13104removeAPI 接受path或key#13115getProperties与getUrl增加 Gen2path参数#13144path方案直接对应 Amplify Gen2 后端通过 data schema 生成的授权路径如protected/{entity_id}/files/*调用方只需传入业务路径而不必关心 identityId 等身份相关前缀的拼接。源码 resolveS3ConfigAndInput 在内部完成“path → 实际 S3 key”的解析对调用方完全透明。2.2 弃用与兼容策略CHANGELOG 与源码类型定义共同确认了弃用策略在 options.ts 中ReadOptionsaccessLevel、targetIdentityId与WriteOptionsaccessLevel均被标记为deprecated This may be removed in the next major version.所有基于key的输入类型GetPropertiesWithKeyOptions、ListAllWithPrefixOptions、GetUrlWithKeyOptions、UploadDataWithKeyOptions等都标注为 deprecated推荐改用对应的*WithPathOptions6.17.0 特别强调弃用的AmplifyServer类型别名与createAmplifyServerContext等函数式 shim 会保留到下一个 major 版本期间已发布的应用代码包括旧的operation: (contextSpec) fetchAuthSession(contextSpec)SSR 写法可以无改动继续编译运行。也就是说v6 内部的演进原则是“新能力向前推进、旧入口按部就班退役”而不是立刻破坏性删除。2.3 源码中的输入分派从 validateStorageOperationInput 与常量 constants.ts定义STORAGE_INPUT_PREFIX prefix、STORAGE_INPUT_KEY key、STORAGE_INPUT_PATH path可以推断底层通过inputType字段区分三种输入形式并据此决定是否拼接keyPrefix。例如 getUrl.ts 中const finalKey inputType STORAGE_INPUT_KEY ? keyPrefix objectKey : objectKey;这条逻辑解释了为什么key需要配合accessLevel拼接前缀protected还会拼入identityId而path直接使用字面路径。三、uploadData深度解析单部分与多部分上传3.1 判定逻辑与默认阈值6.17.0 的内部重构#14798 中可以看到完整的判定流程const dataByteLength byteLength(data); assertValidationError(dataByteLength ! undefined, StorageValidationErrorCode.InvalidUploadSource); assertValidationError(dataByteLength MAX_OBJECT_SIZE, StorageValidationErrorCode.ObjectIsTooLarge); if (dataByteLength DEFAULT_PART_SIZE) { // 单部分走 putObjectJob可取消 } else { // 多部分走 multipart支持暂停/恢复/取消 }相关常量定义在 constants.tsDEFAULT_PART_SIZE 5 MiB单/多部分分界阈值也是分片大小MAX_OBJECT_SIZE 5 TiBS3 单对象上限MAX_PARTS_COUNT 10000最多分片数DEFAULT_QUEUE_SIZE 4并发分片上传队列大小CHANGELOG 5.1.0 中的“当 body 超过 10k 个 parts 时自动加倍 part size”#10820正是基于MAX_PARTS_COUNT约束做的自适应调整保证超大文件也能在分片数量上限内完成。3.2 多部分上传的健壮性修复轨迹多部分上传是 CHANGELOG 中 bug 修复最密集的区域这些修复直接对应源码中 multipart 目录下的子模块4.4.24所有分片完成但无法结束上传时抛错对应completeMultipartUpload失败处理5.1.0分片数超限自动加倍 part size对应 calculatePartSize.ts5.7.0多部分上传无法完成、listParts输出缺少Size、vault 级别 public 文件的多部分上传问题6.6.110 字节数据不再触发多部分上传#139276.9.6Expo/React Native 下上传进度超过总量#14518从目录结构看分片上传的完整链路包括 createMultipartUpload.ts、uploadPart.ts、completeMultipartUpload.ts、abortMultipartUpload.ts配合 uploadCache.ts 实现断点续传缓存的 key 为__uploadInProgress见 constants。3.3 可用的上传选项基于 options.ts 中UploadDataOptions的类型定义uploadData支持以下选项选项类型/取值默认值说明onProgress(event: TransferProgressEvent) void—上传进度回调自 3.1.0 起支持contentTypestring由内容推断6.9.6 修复了 content-type 的推断正确性contentDispositionContentDisposition \| string—下载时响应头设置contentEncodingstring—自 4.1.0 起成为可选参数metadataRecordstring, string—用户自定义元数据preventOverwritebooleanfalse目标 key 已存在时拒绝提交上传checksumAlgorithmcrc-32关闭6.9.0 起支持全量 body 校验和#14383cacheControlstring—6.11.0 起 upload/download/getUrl 三处统一支持#14410useAccelerateEndpointbooleanfalseS3 传输加速端点expectedBucketOwnerstring—桶所有者校验bucketstring \| BucketInfo全局配置覆盖默认桶支持 Gen2 多桶关于preventOverwriteCHANGELOG 6.7.8 修复了“序列化uploadDataOptions哈希时省略不可序列化属性”ba3d3b2避免onProgress等函数属性破坏缓存 key 的稳定性可见上传缓存与防覆盖逻辑是紧密耦合的。3.4 标准用法示例import { uploadData } from aws-amplify/storage; const uploadTask uploadData({ path: media/photos/{entity_id}/my-photo.jpg, // Gen2 授权路径 data: file, // Blob / File / ArrayBuffer / string options: { contentType: image/jpeg, cacheControl: public, max-age31536000, preventOverwrite: false, onProgress: ({ transferredBytes, totalBytes }) { console.log(上传进度 ${transferredBytes}/${totalBytes}); }, }, }); // 任务支持 pause() / resume() / cancel()仅浏览器端多部分上传完整支持 uploadTask.pause(); uploadTask.resume(); uploadTask.cancel(); const result await uploadTask.result; // { key/path, bucket }注意path中的{entity_id}占位符是 Amplify Gen2 授权路径的一部分库内部会结合当前登录用户解析。四、getUrl预签名 URL 的完整能力集4.1 GET 与 PUT 两种用途6.14.0 为getUrl增加了 PUT 方法支持#14740用于生成“预签名上传 URL”。在 internal/getUrl.ts 中可以看到方法分派const operation getUrlOptions?.method ?? GET; if (operation PUT) { // getPresignedPutObjectUrl客户端先拿 URL再自行 PUT 上传 } else { // getPresignedGetObjectUrl下载 URL }典型场景是“移动端/第三方系统不集成 Amplify SDK直接通过 HTTP PUT 上传对象”服务端只负责签发 URL。4.2 过期时间的双重约束getUrl的expiresIn默认值为DEFAULT_PRESIGN_EXPIRATION 900秒15 分钟同时受两个上限约束源码 getUrl.ts绝对上限MAX_URL_EXPIRATION 7 * 24 * 60 * 60 * 10007 天超出会抛UrlExpirationMaxLimitExceed校验错误相对上限实际值取min(请求的 expiresIn, 当前 AWS 临时凭证剩余有效期)避免签发一个比底层凭证更长寿的 URL。这解释了 6.4.3 的修复“credentials expires after 1 hour”#13329——当凭证 1 小时后过期时URL 有效期会被自动截断防止拿到 URL 后因凭证失效而无法使用。4.3 其他重要选项validateObjectExistence: true下载前先执行 HEAD 确认对象存在5.2.0 引入#11154PUT 模式下自动跳过contentDisposition6.6.0 支持可传字符串原样使用或传{ type: attachment|inline, filename }由 constructContentDisposition 构造contentType、cacheControl6.6.0 / 6.11.0 分别引入对应 GET URL 的ResponseContentType/ResponseCacheControl与 PUT URL 的ContentType/CacheControl返回的expiresAt字段让调用方可以精确计算 URL 失效时刻。import { getUrl } from aws-amplify/storage; // 生成 5 分钟有效的下载 URL const downloadUrl await getUrl({ path: media/photos/2026/sunset.jpg, options: { expiresIn: 300, contentType: image/jpeg }, }); // 生成上传 URL需服务端配合提供权限 const putUrl await getUrl({ path: inbox/new-file.bin, options: { method: PUT, expiresIn: 600 }, });五、list的分页、delimiter 与 nextTokenlist是另一条修复与功能密集的线2.2.0支持maxKeys限制列表数量#40994.5.0通过 List API 访问 S3 全部文件5.0.0Storage.list接收nextToken以对齐 API#10626并修正.list响应的类型6.5.0增加delimiter支持#13517默认分隔符为/见 constants 中DEFAULT_DELIMITER6.6.11修复“当 list 结果只包含 CommonPrefix 时 nextToken 不返回”的问题#139336.5.3修复“已定义 prefix 时误传 subPathStrategy”#13618当前list提供两个语义入口list配合prefix的经典列表返回扁平 key 列表与基于pathsubpathStrategy的列表。从 options.ts 的类型定义可以确认ListAllWithPathOptions/ListPaginateWithPathOptions支持subpathStrategy用于控制是否展开子路径。import { list } from aws-amplify/storage; // 分页列举 const { items, nextToken } await list({ path: media/, options: { pageSize: 100, // 拿到 nextToken 后继续翻页 }, }); // 按子路径聚合列举不展开子目录内容 const { items: folders } await list({ path: media/, options: { subpathStrategy: { type: INCLUDE } }, });六、copy、remove、getProperties的功能补全6.1 copy4.2.0加入 copy API#84316.4.0增加path支持#131046.10.0支持 tagging directive#14527CopyWithPathSourceOptions/CopyWithPathDestinationOptions还支持notModifiedSince源对象未修改时间、eTag条件复制与expectedBucketOwner。6.2 remove6.4.0remove接受path或key#131156.12.0为 remove API 增加文件夹删除支持63d77aa文件夹删除的底层实现在 deleteFolderContents.ts 与 generateDeleteObjectsXml.ts先listObjectsV2枚举目录内容再用deleteObjects批量删除入口校验在 validateRemovePath.ts。6.3 getPropertiesgetProperties在 5.3.0 正式引入#11378此前 5.2.x 曾有一次引入后回滚的插曲5.5.0 再次落地#114695.6.0 补上了对应的 user agent action。它返回对象的大小、eTag、contentType 等元数据配合getUrl的validateObjectExistence使用。七、SSR 服务端能力serveruploadData与 AmplifyContext7.1 服务端 uploadData6.15.0 增加了服务端uploadData#14796export { uploadData } from ./apis;服务端实现 server/apis/uploadData.ts 复用了浏览器端的内部uploadData但从类型上隐藏了pause/resume跨隔离服务端请求无法维护状态并注入服务端的readFile/toBase64实现。典型用法来自该文件的 JSDoc 示例// Next.js Route Handler import { runWithAmplifyServerContext } from aws-amplify/adapter-nextjs; import { uploadData } from aws-amplify/storage/server; import { cookies } from next/headers; export async function POST(request: Request) { const formData await request.formData(); const file formData.get(file) as File; const result await runWithAmplifyServerContext({ nextServerContext: { cookies }, operation: (contextSpec) uploadData(contextSpec, { path: uploads/${file.name}, data: file }).result, }); return Response.json(result); }7.2 6.17.0 的显式 AmplifyContext 支持6.17.0#14931为所有 category API 引入了context-first 重载fn(ctx, input)与原有单例形式并存公开的createAmplifyContext(resourcesConfig, libraryOptions?)工厂支持按请求/按租户隔离的上下文aws-amplify/adapter-nextjs的 SSR 实现改为按请求隔离上下文新增类型化误用错误InvalidAmplifyContextError/NoAmplifyContextError新增共享测试入口aws-amplify/core/internals/testing。同时声明了两个兼容性行为变化Resources config 深度冻结Amplify.configure()与createAmplifyContext()之后配置对象从“仅冻结顶层”变为深度冻结。任何在 configure 后修改嵌套配置字段的代码——官方一直不支持——在严格模式下会直接抛错而非静默成功。Peer 最低版本提升aws-amplify/core提升至^6.19.0各 category 包、aws-amplify提升至^6.21.0针对aws-amplify/adapter-nextjs用于防范版本错配。需要注意的是该防线仅在依赖树重新解析时生效——已有 lockfile、npm ci、--legacy-peer-deps安装以及 yarn classic 仅警告的 peer 检查不会重新校验。八、权限解析authenticated 与 groups 的加法合并6.15.0 的 Patch 修复#14793是一个值得展开的细节resolveLocationsForCurrentSession现在会合并 authenticated 与 group 两类权限使allow.authenticated与allow.groups(...)规则对同时处于某个 Cognito 组的用户呈现加法效果与 IAM 行为对齐。此前该函数只取其一导致 StorageBrowser 在两种规则同时存在时隐藏文件夹或低估权限对应 amplify-ui 仓库的 #6930 问题。源码 resolveLocationsForCurrentSession.ts 中的resolvePermissions展示了合并逻辑if (groups) { // ...找到匹配 group 的权限 key return { permission: [ ...new Set([ ...(authenticatedPermission ?? []), ...(groupPermission ?? []), ]), ], }; }实现要点未认证用户只看guest权限已认证且无组时使用authenticated权限已认证且有组时取两者去重合并。同时entityidentity路径如protected/{entity_id}只在已认证且具备 identityId 时展开。九、底层 S3 客户端迁移5.7.0 的技术底座5.7.02023-07-13是一次重要的底层重建CHANGELOG 一次性记录了 8 项 S3 客户端能力自定义 S3 transfer handler#11482基于 XHR 的 transfer handler#11471DOM 级 XML 解析器#11300putObject#11513多部分上传 API#11514listObjectsV2#11504copy/delete/get/head 对象 API#11515集成自定义 S3 client#11542这些能力在源码中均有对应实现s3data 目录下的低层 S3 API 封装、runtime/s3TransferHandler 下的 fetch/xhr 双实现、runtime/xmlParser 下的 dom/pureJs 双实现。包内同时依赖fast-xml-parser、crc-32、smithy/md5-js、buffer等运行时库并通过browser与react-native字段完成环境替换。与完整性相关的后续修复还包括5.7.0预签名 URL 避免双重签名cf51899、RN 中支持body.text()并优化重试6.9.2移除getAmplifyUserAgent()的导入副作用#14433配合sideEffects: false优化 tree-shaking6.11.1更新 AWS SDK 包以解决smithy/config-resolver#146676.11.0预签名 URL 使用 unsigned payload#146366.14.0AWS SDK 升级至 v3.1012.0十、工程化演进构建产物、类型安全与本地测试10.1 构建与产物3.1.0发布 ES2015/ESM 产物bc8610a所有 V3 SDK 调用附加 Amplify user agent3.1.0S3 上传进度上报与多部分上传#45585.0.0使用 tslib 与importHelpers缩小 bundle#10435、移除大部分默认导出#10461、展开*导出以优化 tree-shaking#10555、引入 TypeScript 覆盖率报告机制#105515.0.0优化sideEffects以提升 shake-ability#10375在 package.json 中可以看到对应的最终状态sideEffects: false、browser/react-native双映射、typesVersions子路径类型声明以及ts-coverage脚本阈值 90.31%。10.2 本地测试支持1.1.0 加入了本地测试支持#3806。当前源码在 constants.ts 保留了LOCAL_TESTING_S3_ENDPOINT http://localhost:20005配合 Amplify 本地 mock 服务可在无 AWS 环境下联调。10.3 其他历史修复亮点1.0.30修复多次Amplify.configure/Storage.configure后默认 access level 被错误置为private的问题——默认 level 恒为public#32221.0.24显式声明signatureVersion v4#23794.4.6支持useAccelerateEndpoint、自动调整systemClockOffset#91156.6.8修复 React Native 下 MD5 计算#138366.7.0Storage Browser 的完整性integrity改造#13909十一、版本升级与迁移建议基于 CHANGELOG 的兼容性说明给出以下实操建议锁定统一发布线保持直接安装的aws-amplify/*category 包与aws-amplify处于同一条 release line。文档明确指出混用旧 scoped 包如aws-amplify/auth固定在依赖core ^6.16.2的 6.x 版本与新版 core 是不被支持的。警惕已有 lockfile6.17.0 的 peer 最低版本防线不覆盖npm ci、--legacy-peer-deps与旧 lockfile。升级后建议重新生成 lockfile 或显式升级aws-amplify/core到^6.19.0以上。逐步迁移到pathAPI新代码一律使用path参数存量key/accessLevel代码在 v6 中仍可运行但应规划在下一个 major 前完成迁移。不要在 configure 后修改嵌套配置6.17.0 起配置对象深度冻结此类操作会从静默成功变为抛错。SSR 场景使用 server 子路径aws-amplify/storage/server只暴露uploadData且不暴露pause/resume请通过runWithAmplifyServerContext的operation回调传入contextSpec。十二、延伸阅读本文引用的仓库内关键文件变更日志本体packages/storage/CHANGELOG.md包配置与导出地图packages/storage/package.json浏览器端公开 APIpackages/storage/src/index.ts、服务端入口packages/storage/src/server/index.ts选项类型定义含弃用标记与默认值注释packages/storage/src/providers/s3/types/options.ts上传分派与多部分实现packages/storage/src/providers/s3/apis/internal/uploadData/index.ts预签名 URL 实现packages/storage/src/providers/s3/apis/internal/getUrl.ts权限合并实现packages/storage/src/internals/apis/listPaths/resolveLocationsForCurrentSession.ts常量与分片默认值packages/storage/src/providers/s3/utils/constants.ts底层 S3 数据面客户端packages/storage/src/providers/s3/utils/client/s3data以上全部内容均以当前仓库的实际源码与 CHANGELOG 记录为准文中涉及的版本行为、默认值与兼容性说明对应版本的代码可在仓库对应 tag 中进一步核验。赞分享前端后端移动开发【免费下载链接】amplify-jsA declarative JavaScript library for application development using cloud services.项目地址https://gitcode.com/gh_mirrors/am/amplify-js点击查看免费下载相关推荐OpenProject 中的 Stimulus 控制器开发指南静态注册、动态加载与插件集成约定OpenProject 中的 Stimulus 控制器开发指南静态注册、动态加载与插件集成约定 本文以 OpenProject 官方开发文档 docs/dev前端后端移动开发上一篇React Infinite 使用教程下一篇绝区零自动化框架安装与配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
