 的 API 用法、生命周期回调与双通道上传原理)
Puter.js 文件上传完整指南puter.fs.upload() 的 API 用法、生命周期回调与双通道上传原理【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterputer.fs.upload()是 Puter.jsPuter SDK面向用户文件系统FS的上传入口用于把网页或本地环境中的文件、拖拽条目、Blob等数据写入当前用户自己的 Puter 文件空间。本文以官方 API 文档 upload.md 为骨架结合仓库内 SDK 源码src/puter-js/src/modules/FileSystem/operations/upload/逐一讲解参数语义、init/start/progress/abort回调、失败语义含failedItems与各错误码、目录上传与缩略图生成的平台差异以及签名批量直传 vs 旧版/batch转发两种底层上传通道帮助你写出健壮、可打断、带进度与缩略图的上传代码。适用平台与文档定位该 API 在前置元信息中声明的可用平台为websites、apps、nodejs、workers四类见 upload.md 头部 front-matter。从 SDK 实现看不同环境走的上传通道并不相同web对应 websites、gui、app环境走签名批量直传通道signed batch writenodejs、workers环境走旧版/batch转发通道legacy batch。这一差异直接决定了目录上传能力、错误码形态与进度语义详见后文上传目录的平台差异与双通道原理两节。文档是公开 API 参考正文可直接作为puter.fs.upload()的权威用法说明代码佐证来自仓库源码读者可沿路径自行核对。API 语法与一次上传的执行流程upload是挂载在puter.fs命名空间上的异步操作在 FileSystem/index.js 中注册支持三种调用形态puter.fs.upload(items) puter.fs.upload(items, dirPath) puter.fs.upload(items, dirPath, options)items要上传的内容必填dirPath目标目录可选省略时上传到应用自身根目录options上传行为配置与回调集合可选。从 operations/upload/index.js 的编排逻辑看一次调用内部大致依次经历鉴权若在 web 环境且尚无authToken先调用puter.ui.authenticateWithPuter()完成登录失败则直接 reject目录校验与路径解析目标目录不能是根目录/相对路径会通过getAbsolutePathForApp解析到应用根目录下条目归一化normalizeUploadEntries把多种输入形态扁平化为统一条目列表缩略图准备按选项在浏览器端生成缩略图SDK 会等待这一步完成后再发送文件空间预检非 web 环境且待传总量达到阈值时先查剩余空间不足则提前失败避免上传到一半被服务器拒绝执行上传优先尝试签名批量直传后端不支持返回 404/405/501 等时自动回退到旧版/batch通道。源码注释还特意说明了根目录限制的合理性dirPath /时会以Can not upload to root directory.拒绝省略dirPath与应用相对路径都会归一化到应用的专属目录getAbsolutePathForApp.js。参数一items——被上传的对象官方文档给出的合法类型是InputFileList、FileList、File对象数组或Blob对象数组。对照 types.js 中的UploadItems类型与 entries.js 的归一化实现实际可接受的输入范围更宽输入形态处理方式依据 entries.js 源码DataTransferItemList/DataTransferItem含数组包裹标记为拖拽场景先经puter.ui.getEntriesFromDataTransferItems解析出文件与目录再按目录优先、文件按字节大小升序排序拖拽对象可能携带子目录结构isDirectory、fullPathFileList/ 单个File/File数组摊平为数组并按size升序排序为其补上filepath/fullPath等于文件名单个Blob包装成File类型application/octet-stream文件名来自options.name字符串包装成名为default.txt、类型text/plain的File其他任何类型抛出{ code: field_invalid, message: upload() items parameter is an invalid type }归一化后的条目会在separateFilesAndDirs中被进一步区分目录条目解析finalPath/fullPath去掉前导/拼到dirPath下形成待创建目录路径文件条目依据finalPath/filepath/fullPath/name决定目标位置与文件名大小写不敏感的.ds_store会被自动跳过名字为空则视为仅建空目录options.createFileParent打开时会为嵌套路径逐级生成父目录用uniqueDirs去重。了解这些内部规则有助于正确预估上传结果。例如把File单个对象直接传入时返回单个FSItem而传入多个对象时返回数组——这一单数/复数判定贯穿两种上传通道的收尾逻辑。参数二dirPath——上传目标目录dirPath是一个字符串表示内容要落盘的目录省略时上传到应用自身的根目录传入以/开头的绝对路径则直接作为目标传入相对路径如./uploads会被解析为应用根目录 该相对路径。需要特别注意的是根目录本身/不能作为上传目标SDK 会直接拒绝因为上传语义是往目录里写入条目根目录归用户所有。若dirPath指定的目录尚不存在默认并不会自动创建需要通过createMissingParents或先用puter.fs.mkdir()建好详见下文选项说明。参数三options 与上传生命周期回调options是一组键值对控制命名冲突策略、父目录创建与缩略图行为同时承载整个上传过程的回调。全部可选字段以 JSDoc 形式定义在 types.js 的UploadOptionsOwn中上传编排则在 index.js 中消费。先看官方文档明确列出的五个行为开关选项类型默认值语义overwriteBooleanfalse目标已存在时是否覆盖。为true时dedupeName被忽略签名通道中会强制把重名去重关闭dedupeNameBooleantrue目标已存在且不覆盖时是否自动对文件名去重通常表现为追加序号overwrite: true时该字段无效createMissingParentsBooleanfalse目标父目录不存在时是否自动逐级创建generateThumbnailsBooleanfalse是否在上传前于浏览器端为图片生成缩略图无法解码的文件与生成失败都会被静默跳过thumbnailGeneratorFunction—自定义缩略图生成器(file, context) string \| undefined可返回 Promise覆盖内置图片生成器thumbnailString—备用缩略图data URL 或 URL用于文件没有生成出缩略图的情况超过 2 MiB 的 data URL 会被丢弃补充几个从源码能确认、但文档正文未展开的内部细节createMissingParents的宽松判定在签名通道中只要createMissingAncestors、createMissingParents、createFileParent任一为真或者本次上传本身就包含目录条目dirs.length 0都会自动补建缺失父目录见 signedBatchUpload.js。dedupeName与overwrite的联动签名通道里文件元数据中的dedupeName在覆盖开启时被强制置为falsesignedBatchUpload.js旧版通道的 mkdir/write 操作里dedupe_name仍取options.dedupeName ?? truelegacyBatchUpload.js。两条通道的措辞略有差异但对公开 API 而言行为一致。thumbnail只是兜底当文件生成了缩略图时以生成为准仅当无生成结果时才退而使用thumbnail字段。生命周期回调init / start / progress / abort以下回调用于追踪一次上传的完整生命周期其中operationId是 SDK 为本次上传生成的 UUID因此同一页面并行发起多次上传时可用它区分不同操作、避免把进度串台回调签名触发时机init(operationId, xhr)请求对象已创建、尚未发送时。回调会拿到原始XMLHttpRequest因此可以自行调用xhr.abort()主动取消上传start()上传开始发送字节时无参数progress(operationId, progress)字节发送过程中持续触发progress是0到100之间的百分比数值abort(operationId)上传被中止时一个带进度回调的最小示例官方文档原例puter.fs.upload(items, ./uploads, { progress: (operationId, progress) { console.log(${Math.round(progress)}%); }, });取消的两种途径与差异。通过init拿到的xhr.abort()是主动取消句柄在缩略图等上传准备阶段调用时SDK 会中止准备流程上传不会启动Promise 以{ code: upload_aborted, message: Upload aborted. }拒绝见 index.js 对xhr.abort的覆写它会触发内部AbortController调用options.abort再以upload_aborted拒绝。自定义缩略图生成器收到context.signal中止信号后应当尽快停止工作因为 SDK 在真正发送文件前会等待缩略图准备完成。除文档列出的四个回调外UploadOptions还透传RequestCallbacks层的success与error回调Promise 风格的补充success(items)在成功解析后触发error(e)在失败时触发types.js。使用options.error时注意它只是通知钩子Promise 仍然会以同一个错误拒绝两者并不互斥。返回值与失败语义成功或全量失败绝无半好半坏调用返回一个Promise其成功形态遵循条数即形态items中只有一个条目时resolve 为单个FSItem对象items含多个条目时resolve 为FSItem对象数组任一环节失败时 Promise 一律reject——永远不会 resolve 出一个部分成功 部分错误的混合值index.js 顶层承诺注释明确写死了这一约定。部分失败的细节failedItems当失败发生在单个条目层面而非整个请求层面时拒绝值会额外携带failedItems数组其中每个元素描述一个失败条目path该条目的目标路径message失败原因描述code、status服务端给出时的错误码与 HTTP 状态码。并且部分失败不会回滚已经写入成功的条目会保留只有失败条目需要调用方决定如何补偿重试。全部条目以同因失败时错误码会被上提如果failedItems里的每个条目都以完全相同的code和status失败说明失败原因属于整个请求而非某个具体文件SDK 会把这些字段同时挂在拒绝值本身上见 signedBatchUpload.js 的sharedFailureFields仅当所有失败条目共享同一非空code/status时才上提混合失败则不猜测。最典型的场景是账号存储配额耗尽无论一次传入多少文件上传都会以code: storage_limit_reached、status: 413整体拒绝。调用方只需判断一次error.code即可命中此类情况SDK 内部的promptIfStorageLimitError也会据此弹出空间不足提示见 storageLimitPrompt.js。nodejs / workers 环境下的批次错误码在nodejs与workers上上传走后端转发式的旧/batch端点此时拒绝值携带一组稳定的批次级code实现于 legacyBatchUpload.js错误码含义batch_upload_failed批次内所有操作都失败未写入任何内容batch_upload_partially_failed部分操作成功、部分失败failedCount与totalCount分别说明失败数与总数results按发送顺序保存每个操作的原始结果batch_upload_no_results请求本身成功2xx但服务端未报告任何写入结果旧版通道以 HTTP218作为批次内至少一个操作失败的标志SDK 会把响应体中的操作结果逐个按error: true或非 200 状态判为失败isFailedBatchResult再汇总为上述buildBatchFailureError结构若options.strict为真write()等内部操作使用则直接抛出那个失败操作本身而不是批次汇总。上传目录平台差异与规避方案目录上传含拖入的目录条目以及createFileParent隐式建目录只在websites与apps上受支持。这与前文所述的通道差异直接相关签名批量直传通道会把目录条目作为type: directory的注册项发送其contentType为application/x-puter-directorysize为 0见 signedBatchUpload.js后端据此建立目录树旧版/batch通道本质是逐条 mkdir/write 请求 文件字节的 multipart 转发无法创建目录树。因此目录上传一旦落入该通道典型即nodejs/workers会直接以batch_upload_failed拒绝。推荐规避方案在nodejs/workers中不要试图上传目录对象而是先用puter.fs.mkdir()建好目录再逐个把目录内的文件用upload(file, dirPath)传进去。这也是官方文档明确建议的做法。缩略图内置生成器、自定义生成器与 PDFgenerateThumbnails打开后SDK 会在浏览器端为浏览器可解码的图片生成缩略图。内置生成器实现位于 thumbnails.js其行为可以从常量与算法还原只在存在document且输入是File时工作并通过 MIME 前缀或扩展名.png/.jpg/.jpeg/.gif/.bmp/.webp/.tiff/.avif/.jfif判断是否为图片用canvas等比缩放优先尝试image/webp质量 0.85→image/jpeg质量 0.8→image/png三种廉价编码逐步把边长从默认128px折半最小32px直到编码结果小于 2 MiBMAX_THUMBNAIL_BYTES 2 * 1024 * 1024整个过程是尽力而为的任何一步失败都返回undefined绝不阻断原文件上传。PDF 与内置生成器的边界内置生成器不含 PDF 渲染能力SDK 未内嵌 PDF.jsPuter 桌面端对 PDF 的预览图支持是桌面产品单独提供的。需要 PDF 缩略图的应用应当自带渲染器通过thumbnailGenerator挂入并把其余文件委托给内置生成器——官方示例正是这么写的const file new File([Hello!], hello.txt, { type: text/plain }); await puter.fs.upload(file, ./, { thumbnailGenerator: async (file, { defaultGenerator, signal }) { if (signal.aborted) return undefined; return defaultGenerator(file); }, });thumbnailGenerator回调约定见 types.js 的ThumbnailGeneratorContext每个文件至多调用一次可返回 Promise返回缩略图 data URL 或普通 URL返回undefined表示跳过该文件的缩略图回调抛出的异常会被忽略包装进 try/catch不会阻断上传context.defaultGenerator(file)即上述内置图片生成器context.signal是上传准备期的AbortSignal取消时会置为 aborted自定义生成器应据此尽早停手并自行设定时间与资源预算存在自定义生成器时即使不写generateThumbnails也会触发缩略图准备generateThumbnails()的触发条件是二者其一为真。缩略图传输的容错规则在签名直传通道中data URL 形态的缩略图会先被转成 Blob、用独立的签名 URL 上传到对象存储再在完成阶段引用其thumbnailUrl见 signedBatchUpload.js 的uploadSignedFileTask。这里的容错边界非常清晰单独的缩略图传输若失败或超过 5 秒THUMBNAIL_UPLOAD_TIMEOUT_MS 5000见 constants.js会被跳过原文件继续照常上传显式的上传取消仍会中止整个流程原文件字节传输本身的错误则照常以 reject 暴露。也就是说缩略图只是锦上添花任何缩略图问题都不应让用户的核心上传失败。底层原理签名批量直传与旧版 /batch 双通道puter.fs.upload的实现体现了 Puter 上传体系的两次架构演进。理解这两条通道有助于排查进度异常与错误码差异。通道一签名批量直传signed batch write针对web/gui/app环境SDK 首选 signedBatchUpload.js 描述的流程把全部条目按每批 500 个分块SIGNED_BATCH_REQUEST_CHUNK_SIZE以块组流水线方式并发4个 chunkSIGNED_BATCH_CHUNK_PIPELINE_CONCURRENCYPOST 到/fs/startBatchWrite为每个文件换取临时签名存储 URL文件字节直接由客户端 PUT 到签名 URL不经过 Puter 服务器中转文件级并发8SIGNED_BATCH_FILE_UPLOAD_CONCURRENCY大文件按服务端声明的分片方案走 multipart分片签名不足时调/fs/signMultipartParts补充分片上传并发同为8SIGNED_MULTIPART_PART_UPLOAD_CONCURRENCY并收集每个分片的 ETag全部字节就绪后以uploadIdsessionId 分片 ETag 调/fs/completeBatchWrite完成落盘若整批完成请求失败则退化为对每个条目单独调/fs/completeWrite重试任一失败文件会调/fs/abortWrite清理其服务端会话最终汇总为带failedItems的partial错误并上提共享code/status。SDK 会把后端是否支持签名直传缓存在模块实例上signedBatchWriteSupported一旦某次/fs/startBatchWrite返回 404/405/501 等能力缺失信号isSignedBatchWriteUnavailableError本次立即回退到旧通道且后续上传永久走旧通道避免重复探测。反过来一次成功会把能力标记为可用。通道二旧版 /batch 转发legacyBatchUpload.js 是能力缺失或环境不支持nodejs/workers时的退路也是nodejs/workers的唯一通道把mkdir与write两类操作序列化进同一份FormData连同全部文件字节一次性 multipart POST 到/batch由服务器代为转发字节到云端存储目录会按路径长度逆序深的在前整理并用$dir_i占位符把嵌套文件的路径改写为相对于父目录的形式进度被拆成两段客户端 → 服务器的字节xhr.upload事件与服务器 → 云端的字节通过 socket 的upload.progress事件 100ms 轮询两者相加得到整体百分比。因此在nodejs/workers环境中若 socket 不可用云端段的进度自然不前进——注释明确说明这是预期行为也因此总字节量被按 2 倍估算totalSize * 2一份给客户端上传、一份给服务器转发operation_id会写进 FormData 与每个操作用于服务端与进度事件的对账。空间预检与其他守护逻辑无论走哪条通道上传前都有几道前置闸门index.js空间预检仅非 web 环境执行。当本次上传总量 ≥ 1 MiBSPACE_CHECK_MIN_BYTES低于该阈值时预检往返开销大于省下的成本时先调用puter.fs.space()对比capacity - used与totalSize不足则提前以NOT_ENOUGH_SPACE拒绝空上传拦截归一化后若既无文件也无目录以EMPTY_UPLOADNo files or directories to upload.拒绝一次性start两条通道共用一个startCallbackFired标志确保签名通道失败回退到旧通道后start回调不会重复触发。服务端对应的落地实现可继续追读 FSController.ts 与 FSService.ts含/fs/startBatchWrite、/fs/completeBatchWrite、/fs/abortWrite等路由与业务逻辑。完整可运行示例示例一从文件选择框上传官方原例html body !-- 在真实页面中请以你的部署方式加载 Puter.js SDK构建产物见 src/puter-js/ -- input typefile idfile-input / script // File input let fileInput document.getElementById(file-input); // Upload the file when the user selects it fileInput.onchange () { puter.fs.upload(fileInput.files).then((file) { puter.print(File uploaded successfully to: ${file.path}); }) }; /script /body /htmlfileInput.files是一个FileList被归一化后上传到应用根目录因为只选了一个文件成功回调里的file是单个FSItem可直接读取其path等属性。示例二上传到指定目录 进度展示 显式取消const input document.getElementById(file-input); input.onchange async () { // 通过 init 拿到句柄稍后用于取消 let uploadXhr; try { const uploaded await puter.fs.upload(input.files, ./uploads, { createMissingParents: true, // 目标目录不存在时自动创建 generateThumbnails: true, // 浏览器端为图片生成缩略图 overwrite: false, // 不覆盖已存在文件 init: (operationId, xhr) { uploadXhr xhr; // 保留取消句柄 console.log(upload started with operationId:, operationId); }, start: () console.log(sending...), progress: (operationId, progress) { console.log(upload ${operationId}: ${Math.round(progress)}%); }, abort: (operationId) console.log(aborted:, operationId), }); // 多文件时 uploaded 是 FSItem[]单文件时是 FSItem const items Array.isArray(uploaded) ? uploaded : [uploaded]; console.log(ok:, items.map((item) item.path)); } catch (e) { if (e.code upload_aborted) { console.log(用户取消了上传); } else if (e.code storage_limit_reached e.status 413) { console.log(存储配额不足); } else { console.error(部分/全部失败, e.failedItems ?? e); } } }; // 例如点击按钮时取消 function cancelUpload() { if (uploadXhr) uploadXhr.abort(); }示例三Blob 与字符串内容的上传单文件上传时 resolve 为单个FSItem这也让用代码构造内容再上传变得非常方便Blob 以options.name命名字符串默认落盘为default.txt// Blob需要显式命名 const blob new Blob([hello from blob], { type: text/plain }); await puter.fs.upload(blob, /Documents, { name: note.txt }); // 字符串直接作为文本内容 await puter.fs.upload(hello from puter, /Documents);示例四nodejs / workers 中上传目录内文件由于旧版/batch无法建目录树nodejs里遇到目录应拆解为先 mkdir、再逐个上传文件// nodejs 环境示意对目录下每个文件 await puter.fs.mkdir({ path: /projects/my-app }); for (const localFilePath of filesToUpload) { await puter.fs.upload(localFilePath, /projects/my-app); }常见错误码速查错误码 / 形态出现场景处理建议field_invaliditems不是任何受支持的类型校验输入传File/Blob/FileList/DataTransferItemList或字符串EMPTY_UPLOAD归一化后没有任何文件或目录检查拖拽解析结果是否为空NOT_ENOUGH_SPACE非 web 环境空间预检不足≥1 MiB 时触发提示用户清理空间或升级配额upload_abortedUpload aborted.准备期通过init句柄取消属预期取消按用户主动放弃处理storage_limit_reached/status: 413配额耗尽导致整批被拒共享code/status被上提一次判断e.code即可不必遍历failedItemsbatch_upload_failednodejs/workers 旧通道整批失败含目录上传目录场景改用mkdir 逐文件上传batch_upload_partially_failed旧通道部分成功部分失败读取failedItems/failedCount/totalCount重试失败项成功项不会回滚batch_upload_no_results旧通道 2xx 但服务端未报告写入结果用stat/readdir核对目标是否实际写入延伸阅读API 文档原文FS/upload.md文件系统总览FS返回对象形态FSItem配套操作puter.fs.mkdir()、puter.fs.write()SDK 上传源码operations/upload/编排 index.js、归一化 entries.js、缩略图 thumbnails.js、签名通道 signedBatchUpload.js、旧通道 legacyBatchUpload.js、常量 constants.js相关测试upload/index.test.js、upload/thumbnailUpload.test.js、upload/signedBatchUpload.test.js服务端实现FSController.ts、FSService.ts【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Puter.js 文件上传完整指南puter.fs.upload() 的 API 用法、生命周期回调与双通道上传原理【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puterputer.fs.upload()是 Puter.jsPuter SDK面向用户文件系统FS的上传入口用于把网页或本地环境中的文件、拖拽条目、Blob等数据写入当前用户自己的 Puter 文件空间。本文以官方 API 文档 upload.md 为骨架结合仓库内 SDK 源码src/puter-js/src/modules/FileSystem/operations/upload/逐一讲解参数语义、init/start/progress/abort回调、失败语义含failedItems与各错误码、目录上传与缩略图生成的平台差异以及签名批量直传 vs 旧版/batch转发两种底层上传通道帮助你写出健壮、可打断、带进度与缩略图的上传代码。适用平台与文档定位该 API 在前置元信息中声明的可用平台为websites、apps、nodejs、workers四类见 upload.md 头部 front-matter。从 SDK 实现看不同环境走的上传通道并不相同web对应 websites、gui、app环境走签名批量直传通道signed batch writenodejs、workers环境走旧版/batch转发通道legacy batch。这一差异直接决定了目录上传能力、错误码形态与进度语义详见后文上传目录的平台差异与双通道原理两节。文档是公开 API 参考正文可直接作为puter.fs.upload()的权威用法说明代码佐证来自仓库源码读者可沿路径自行核对。API 语法与一次上传的执行流程upload是挂载在puter.fs命名空间上的异步操作在 FileSystem/index.js 中注册支持三种调用形态puter.fs.upload(items) puter.fs.upload(items, dirPath) puter.fs.upload(items, dirPath, options)items要上传的内容必填dirPath目标目录可选省略时上传到应用自身根目录options上传行为配置与回调集合可选。从 operations/upload/index.js 的编排逻辑看一次调用内部大致依次经历鉴权若在 web 环境且尚无authToken先调用puter.ui.authenticateWithPuter()完成登录失败则直接 reject目录校验与路径解析目标目录不能是根目录/相对路径会通过getAbsolutePathForApp解析到应用根目录下条目归一化normalizeUploadEntries把多种输入形态扁平化为统一条目列表缩略图准备按选项在浏览器端生成缩略图SDK 会等待这一步完成后再发送文件空间预检非 web 环境且待传总量达到阈值时先查剩余空间不足则提前失败避免上传到一半被服务器拒绝执行上传优先尝试签名批量直传后端不支持返回 404/405/501 等时自动回退到旧版/batch通道。源码注释还特意说明了根目录限制的合理性dirPath /时会以Can not upload to root directory.拒绝省略dirPath与应用相对路径都会归一化到应用的专属目录getAbsolutePathForApp.js。参数一items——被上传的对象官方文档给出的合法类型是InputFileList、FileList、File对象数组或Blob对象数组。对照 types.js 中的UploadItems类型与 entries.js 的归一化实现实际可接受的输入范围更宽输入形态处理方式依据 entries.js 源码DataTransferItemList/DataTransferItem含数组包裹标记为拖拽场景先经puter.ui.getEntriesFromDataTransferItems解析出文件与目录再按目录优先、文件按字节大小升序排序拖拽对象可能携带子目录结构isDirectory、fullPathFileList/ 单个File/File数组摊平为数组并按size升序排序为其补上filepath/fullPath等于文件名单个Blob包装成File类型application/octet-stream文件名来自options.name字符串包装成名为default.txt、类型text/plain的File其他任何类型抛出{ code: field_invalid, message: upload() items parameter is an invalid type }归一化后的条目会在separateFilesAndDirs中被进一步区分目录条目解析finalPath/fullPath去掉前导/拼到dirPath下形成待创建目录路径文件条目依据finalPath/filepath/fullPath/name决定目标位置与文件名大小写不敏感的.ds_store会被自动跳过名字为空则视为仅建空目录options.createFileParent打开时会为嵌套路径逐级生成父目录用uniqueDirs去重。了解这些内部规则有助于正确预估上传结果。例如把File单个对象直接传入时返回单个FSItem而传入多个对象时返回数组——这一单数/复数判定贯穿两种上传通道的收尾逻辑。参数二dirPath——上传目标目录dirPath是一个字符串表示内容要落盘的目录省略时上传到应用自身的根目录传入以/开头的绝对路径则直接作为目标传入相对路径如./uploads会被解析为应用根目录 该相对路径。需要特别注意的是根目录本身/不能作为上传目标SDK 会直接拒绝因为上传语义是往目录里写入条目根目录归用户所有。若dirPath指定的目录尚不存在默认并不会自动创建需要通过createMissingParents或先用puter.fs.mkdir()建好详见下文选项说明。参数三options 与上传生命周期回调options是一组键值对控制命名冲突策略、父目录创建与缩略图行为同时承载整个上传过程的回调。全部可选字段以 JSDoc 形式定义在 types.js 的UploadOptionsOwn中上传编排则在 index.js 中消费。先看官方文档明确列出的五个行为开关选项类型默认值语义overwriteBooleanfalse目标已存在时是否覆盖。为true时dedupeName被忽略签名通道中会强制把重名去重关闭dedupeNameBooleantrue目标已存在且不覆盖时是否自动对文件名去重通常表现为追加序号overwrite: true时该字段无效createMissingParentsBooleanfalse目标父目录不存在时是否自动逐级创建generateThumbnailsBooleanfalse是否在上传前于浏览器端为图片生成缩略图无法解码的文件与生成失败都会被静默跳过thumbnailGeneratorFunction—自定义缩略图生成器(file, context) string \| undefined可返回 Promise覆盖内置图片生成器thumbnailString—备用缩略图data URL 或 URL用于文件没有生成出缩略图的情况超过 2 MiB 的 data URL 会被丢弃补充几个从源码能确认、但文档正文未展开的内部细节createMissingParents的宽松判定在签名通道中只要createMissingAncestors、createMissingParents、createFileParent任一为真或者本次上传本身就包含目录条目dirs.length 0都会自动补建缺失父目录见 signedBatchUpload.js。dedupeName与overwrite的联动签名通道里文件元数据中的dedupeName在覆盖开启时被强制置为falsesignedBatchUpload.js旧版通道的 mkdir/write 操作里dedupe_name仍取options.dedupeName ?? truelegacyBatchUpload.js。两条通道的措辞略有差异但对公开 API 而言行为一致。thumbnail只是兜底当文件生成了缩略图时以生成为准仅当无生成结果时才退而使用thumbnail字段。生命周期回调init / start / progress / abort以下回调用于追踪一次上传的完整生命周期其中operationId是 SDK 为本次上传生成的 UUID因此同一页面并行发起多次上传时可用它区分不同操作、避免把进度串台回调签名触发时机init(operationId, xhr)请求对象已创建、尚未发送时。回调会拿到原始XMLHttpRequest因此可以自行调用xhr.abort()主动取消上传start()上传开始发送字节时无参数progress(operationId, progress)字节发送过程中持续触发progress是0到100之间的百分比数值abort(operationId)上传被中止时一个带进度回调的最小示例官方文档原例puter.fs.upload(items, ./uploads, { progress: (operationId, progress) { console.log(${Math.round(progress)}%); }, });取消的两种途径与差异。通过init拿到的xhr.abort()是主动取消句柄在缩略图等上传准备阶段调用时SDK 会中止准备流程上传不会启动Promise 以{ code: upload_aborted, message: Upload aborted. }拒绝见 index.js 对xhr.abort的覆写它会触发内部AbortController调用options.abort再以upload_aborted拒绝。自定义缩略图生成器收到context.signal中止信号后应当尽快停止工作因为 SDK 在真正发送文件前会等待缩略图准备完成。除文档列出的四个回调外UploadOptions还透传RequestCallbacks层的success与error回调Promise 风格的补充success(items)在成功解析后触发error(e)在失败时触发types.js。使用options.error时注意它只是通知钩子Promise 仍然会以同一个错误拒绝两者并不互斥。返回值与失败语义成功或全量失败绝无半好半坏调用返回一个Promise其成功形态遵循条数即形态items中只有一个条目时resolve 为单个FSItem对象items含多个条目时resolve 为FSItem对象数组任一环节失败时 Promise 一律reject——永远不会 resolve 出一个部分成功 部分错误的混合值index.js 顶层承诺注释明确写死了这一约定。部分失败的细节failedItems当失败发生在单个条目层面而非整个请求层面时拒绝值会额外携带failedItems数组其中每个元素描述一个失败条目path该条目的目标路径message失败原因描述code、status服务端给出时的错误码与 HTTP 状态码。并且部分失败不会回滚已经写入成功的条目会保留只有失败条目需要调用方决定如何补偿重试。全部条目以同因失败时错误码会被上提如果failedItems里的每个条目都以完全相同的code和status失败说明失败原因属于整个请求而非某个具体文件SDK 会把这些字段同时挂在拒绝值本身上见 signedBatchUpload.js 的sharedFailureFields仅当所有失败条目共享同一非空code/status时才上提混合失败则不猜测。最典型的场景是账号存储配额耗尽无论一次传入多少文件上传都会以code: storage_limit_reached、status: 413整体拒绝。调用方只需判断一次error.code即可命中此类情况SDK 内部的promptIfStorageLimitError也会据此弹出空间不足提示见 storageLimitPrompt.js。nodejs / workers 环境下的批次错误码在nodejs与workers上上传走后端转发式的旧/batch端点此时拒绝值携带一组稳定的批次级code实现于 legacyBatchUpload.js错误码含义batch_upload_failed批次内所有操作都失败未写入任何内容batch_upload_partially_failed部分操作成功、部分失败failedCount与totalCount分别说明失败数与总数results按发送顺序保存每个操作的原始结果batch_upload_no_results请求本身成功2xx但服务端未报告任何写入结果旧版通道以 HTTP218作为批次内至少一个操作失败的标志SDK 会把响应体中的操作结果逐个按error: true或非 200 状态判为失败isFailedBatchResult再汇总为上述buildBatchFailureError结构若options.strict为真write()等内部操作使用则直接抛出那个失败操作本身而不是批次汇总。上传目录平台差异与规避方案目录上传含拖入的目录条目以及createFileParent隐式建目录只在websites与apps上受支持。这与前文所述的通道差异直接相关签名批量直传通道会把目录条目作为type: directory的注册项发送其contentType为application/x-puter-directorysize为 0见 signedBatchUpload.js后端据此建立目录树旧版/batch通道本质是逐条 mkdir/write 请求 文件字节的 multipart 转发无法创建目录树。因此目录上传一旦落入该通道典型即nodejs/workers会直接以batch_upload_failed拒绝。推荐规避方案在nodejs/workers中不要试图上传目录对象而是先用puter.fs.mkdir()建好目录再逐个把目录内的文件用upload(file, dirPath)传进去。这也是官方文档明确建议的做法。缩略图内置生成器、自定义生成器与 PDFgenerateThumbnails打开后SDK 会在浏览器端为浏览器可解码的图片生成缩略图。内置生成器实现位于 thumbnails.js其行为可以从常量与算法还原只在存在document且输入是File时工作并通过 MIME 前缀或扩展名.png/.jpg/.jpeg/.gif/.bmp/.webp/.tiff/.avif/.jfif判断是否为图片用canvas等比缩放优先尝试image/webp质量 0.85→image/jpeg质量 0.8→image/png三种廉价编码逐步把边长从默认128px折半最小32px直到编码结果小于 2 MiBMAX_THUMBNAIL_BYTES 2 * 1024 * 1024整个过程是尽力而为的任何一步失败都返回undefined绝不阻断原文件上传。PDF 与内置生成器的边界内置生成器不含 PDF 渲染能力SDK 未内嵌 PDF.jsPuter 桌面端对 PDF 的预览图支持是桌面产品单独提供的。需要 PDF 缩略图的应用应当自带渲染器通过thumbnailGenerator挂入并把其余文件委托给内置生成器——官方示例正是这么写的const file new File([Hello!], hello.txt, { type: text/plain }); await puter.fs.upload(file, ./, { thumbnailGenerator: async (file, { defaultGenerator, signal }) { if (signal.aborted) return undefined; return defaultGenerator(file); }, });thumbnailGenerator回调约定见 types.js 的ThumbnailGeneratorContext每个文件至多调用一次可返回 Promise返回缩略图 data URL 或普通 URL返回undefined表示跳过该文件的缩略图回调抛出的异常会被忽略包装进 try/catch不会阻断上传context.defaultGenerator(file)即上述内置图片生成器context.signal是上传准备期的AbortSignal取消时会置为 aborted自定义生成器应据此尽早停手并自行设定时间与资源预算存在自定义生成器时即使不写generateThumbnails也会触发缩略图准备generateThumbnails()的触发条件是二者其一为真。缩略图传输的容错规则在签名直传通道中data URL 形态的缩略图会先被转成 Blob、用独立的签名 URL 上传到对象存储再在完成阶段引用其thumbnailUrl见 signedBatchUpload.js 的uploadSignedFileTask。这里的容错边界非常清晰单独的缩略图传输若失败或超过 5 秒THUMBNAIL_UPLOAD_TIMEOUT_MS 5000见 constants.js会被跳过原文件继续照常上传显式的上传取消仍会中止整个流程原文件字节传输本身的错误则照常以 reject 暴露。也就是说缩略图只是锦上添花任何缩略图问题都不应让用户的核心上传失败。底层原理签名批量直传与旧版 /batch 双通道puter.fs.upload的实现体现了 Puter 上传体系的两次架构演进。理解这两条通道有助于排查进度异常与错误码差异。通道一签名批量直传signed batch write针对web/gui/app环境SDK 首选 signedBatchUpload.js 描述的流程把全部条目按每批 500 个分块SIGNED_BATCH_REQUEST_CHUNK_SIZE以块组流水线方式并发4个 chunkSIGNED_BATCH_CHUNK_PIPELINE_CONCURRENCYPOST 到/fs/startBatchWrite为每个文件换取临时签名存储 URL文件字节直接由客户端 PUT 到签名 URL不经过 Puter 服务器中转文件级并发8SIGNED_BATCH_FILE_UPLOAD_CONCURRENCY大文件按服务端声明的分片方案走 multipart分片签名不足时调/fs/signMultipartParts补充分片上传并发同为8SIGNED_MULTIPART_PART_UPLOAD_CONCURRENCY并收集每个分片的 ETag全部字节就绪后以uploadIdsessionId 分片 ETag 调/fs/completeBatchWrite完成落盘若整批完成请求失败则退化为对每个条目单独调/fs/completeWrite重试任一失败文件会调/fs/abortWrite清理其服务端会话最终汇总为带failedItems的partial错误并上提共享code/status。SDK 会把后端是否支持签名直传缓存在模块实例上signedBatchWriteSupported一旦某次/fs/startBatchWrite返回 404/405/501 等能力缺失信号isSignedBatchWriteUnavailableError本次立即回退到旧通道且后续上传永久走旧通道避免重复探测。反过来一次成功会把能力标记为可用。通道二旧版 /batch 转发legacyBatchUpload.js 是能力缺失或环境不支持nodejs/workers时的退路也是nodejs/workers的唯一通道把mkdir与write两类操作序列化进同一份FormData连同全部文件字节一次性 multipart POST 到/batch由服务器代为转发字节到云端存储目录会按路径长度逆序深的在前整理并用$dir_i占位符把嵌套文件的路径改写为相对于父目录的形式进度被拆成两段客户端 → 服务器的字节xhr.upload事件与服务器 → 云端的字节通过 socket 的upload.progress事件 100ms 轮询两者相加得到整体百分比。因此在nodejs/workers环境中若 socket 不可用云端段的进度自然不前进——注释明确说明这是预期行为也因此总字节量被按 2 倍估算totalSize * 2一份给客户端上传、一份给服务器转发operation_id会写进 FormData 与每个操作用于服务端与进度事件的对账。空间预检与其他守护逻辑无论走哪条通道上传前都有几道前置闸门index.js空间预检仅非 web 环境执行。当本次上传总量 ≥ 1 MiBSPACE_CHECK_MIN_BYTES低于该阈值时预检往返开销大于省下的成本时先调用puter.fs.space()对比capacity - used与totalSize不足则提前以NOT_ENOUGH_SPACE拒绝空上传拦截归一化后若既无文件也无目录以EMPTY_UPLOADNo files or directories to upload.拒绝一次性start两条通道共用一个startCallbackFired标志确保签名通道失败回退到旧通道后start回调不会重复触发。服务端对应的落地实现可继续追读 FSController.ts 与 FSService.ts含/fs/startBatchWrite、/fs/completeBatchWrite、/fs/abortWrite等路由与业务逻辑。完整可运行示例示例一从文件选择框上传官方原例html body !-- 在真实页面中请以你的部署方式加载 Puter.js SDK构建产物见 src/puter-js/ -- input typefile idfile-input / script // File input let fileInput document.getElementById(file-input); // Upload the file when the user selects it fileInput.onchange () { puter.fs.upload(fileInput.files).then((file) { puter.print(File uploaded successfully to: ${file.path}); }) }; /script /body /htmlfileInput.files是一个FileList被归一化后上传到应用根目录因为只选了一个文件成功回调里的file是单个FSItem可直接读取其path等属性。示例二上传到指定目录 进度展示 显式取消const input document.getElementById(file-input); input.onchange async () { // 通过 init 拿到句柄稍后用于取消 let uploadXhr; try { const uploaded await puter.fs.upload(input.files, ./uploads, { createMissingParents: true, // 目标目录不存在时自动创建 generateThumbnails: true, // 浏览器端为图片生成缩略图 overwrite: false, // 不覆盖已存在文件 init: (operationId, xhr) { uploadXhr xhr; // 保留取消句柄 console.log(upload started with operationId:, operationId); }, start: () console.log(sending...), progress: (operationId, progress) { console.log(upload ${operationId}: ${Math.round(progress)}%); }, abort: (operationId) console.log(aborted:, operationId), }); // 多文件时 uploaded 是 FSItem[]单文件时是 FSItem const items Array.isArray(uploaded) ? uploaded : [uploaded]; console.log(ok:, items.map((item) item.path)); } catch (e) { if (e.code upload_aborted) { console.log(用户取消了上传); } else if (e.code storage_limit_reached e.status 413) { console.log(存储配额不足); } else { console.error(部分/全部失败, e.failedItems ?? e); } } }; // 例如点击按钮时取消 function cancelUpload() { if (uploadXhr) uploadXhr.abort(); }示例三Blob 与字符串内容的上传单文件上传时 resolve 为单个FSItem这也让用代码构造内容再上传变得非常方便Blob 以options.name命名字符串默认落盘为default.txt// Blob需要显式命名 const blob new Blob([hello from blob], { type: text/plain }); await puter.fs.upload(blob, /Documents, { name: note.txt }); // 字符串直接作为文本内容 await puter.fs.upload(hello from puter, /Documents);示例四nodejs / workers 中上传目录内文件由于旧版/batch无法建目录树nodejs里遇到目录应拆解为先 mkdir、再逐个上传文件// nodejs 环境示意对目录下每个文件 await puter.fs.mkdir({ path: /projects/my-app }); for (const localFilePath of filesToUpload) { await puter.fs.upload(localFilePath, /projects/my-app); }常见错误码速查错误码 / 形态出现场景处理建议field_invaliditems不是任何受支持的类型校验输入传File/Blob/FileList/DataTransferItemList或字符串EMPTY_UPLOAD归一化后没有任何文件或目录检查拖拽解析结果是否为空NOT_ENOUGH_SPACE非 web 环境空间预检不足≥1 MiB 时触发提示用户清理空间或升级配额upload_abortedUpload aborted.准备期通过init句柄取消属预期取消按用户主动放弃处理storage_limit_reached/status: 413配额耗尽导致整批被拒共享code/status被上提一次判断e.code即可不必遍历failedItemsbatch_upload_failednodejs/workers 旧通道整批失败含目录上传目录场景改用mkdir 逐文件上传batch_upload_partially_failed旧通道部分成功部分失败读取failedItems/failedCount/totalCount重试失败项成功项不会回滚batch_upload_no_results旧通道 2xx 但服务端未报告写入结果用stat/readdir核对目标是否实际写入延伸阅读API 文档原文FS/upload.md文件系统总览FS返回对象形态FSItem配套操作puter.fs.mkdir()、puter.fs.write()SDK 上传源码operations/upload/编排 index.js、归一化 entries.js、缩略图 thumbnails.js、签名通道 signedBatchUpload.js、旧通道 legacyBatchUpload.js、常量 constants.js相关测试upload/index.test.js、upload/thumbnailUpload.test.js、upload/signedBatchUpload.test.js服务端实现FSController.ts、FSService.ts【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
