puter.fs.rename() 完全指南：在 Puter 云文件系统中重命名文件与目录

puter.fs.rename() 完全指南在 Puter 云文件系统中重命名文件与目录【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter导读puter.fs.rename()是 Puter 云端存储Cloud StorageAPI 提供的文件重命名方法用于在用户自己的 Puter 文件系统中为文件或目录更换名称。本文以官方文档 rename.md 为主体结合 puter-js SDK 与后端 FSController 的源码实现完整讲解该方法的调用语法、参数规则、相对路径解析逻辑、返回对象以及底层/rename请求链帮助你在网站应用、Puter App、Node.js 与 Workers 场景中正确落地重命名功能。读完本文你将掌握用路径或 UID 两种方式重命名条目、理解应用根目录与new_name请求体的真实含义并知道重命名后的缓存同步机制。一、方法概述puter.fs.rename()用于重命名 Puter 云存储中的一个文件或目录。它只改变条目的名称不改变条目所在的父目录位置如果需要同时移动位置应使用move操作而rename与move也被封装为 SDK 中各自独立的操作见 FileSystem 模块入口。该 API 支持四种运行平台websites浏览器网站、appsPuter App、nodejsNode.js 环境、workersPuter Workers因此同一套调用方式既可用于网页端脚本也可用于服务端环境。官方文档页面对该方法的一句话定义是在 Puter 云存储中修改文件或目录的名称。从源码层面看它最终向后端发送一个 POST 到/rename接口的请求见 operations/rename.js。二、调用语法与函数签名puter.fs.rename()支持位置参数与单一 options 对象两种写法与 puter-js 中所有文件系统操作保持一致相关调用规范见 operations/scaffold.js 中的parseOperationArgs// 形式一位置参数 puter.fs.rename(path, newName) // 形式二options 对象 puter.fs.rename(options)从 SDK 的类型声明operations/rename.js 中的 JSDoc overload与 FileSystem/types.js 的RenameOptions定义看函数还兼容以下两种变体位置参数形式允许最后挂接 legacy 成功/失败回调// 位置参数 成功/失败回调legacy 风格 puter.fs.rename(path, newName, success, error) // options 对象本身可携带 success / error 回调 puter.fs.rename({ path, newName, success, error })所有形式的调用都会返回一个 Promise。三、参数详解位置参数形式参数类型必填说明pathstring是要重命名的文件或目录路径。若path不是绝对路径将相对于应用根目录解析详见下文路径解析规则。newNamestring是该文件或目录的新名称。options 对象形式options 对象中支持的字段同时参考 types.js字段类型必填说明pathstring以 options 作为唯一参数时必填要重命名的文件或目录的路径。uidstring与path二选一要重命名的文件或目录的 UID可替代path使用。newNamestring以 options 作为唯一参数时必填该文件或目录的新名称。successfunction否可选的成功回调接收重命名后的 FSItem。errorfunction否可选的失败回调。excludeSocketID/original_client_socket_idstring否请求体字段用于标识来源 socket帮助客户端跳过对自身操作的缓存失效处理。在 SDK 实现中请求体的组装逻辑见 operations/rename.js如下new_name通过firstDefined(options, newName, new_name)取值即优先读取 camelCase 的newName兼容遗留的 snake_case 拼写new_namefirstDefined定义见 operations/scaffold.js条目定位遵循uid优先于path只要options.uid ! undefined请求体就携带uid否则携带经getAbsolutePathForApp解析过的path。也就是说一个合法的重命名请求体在服务端收到的核心字段是{ uid: …, new_name: 新名称, original_client_socket_id: … }或{ path: /…, new_name: 新名称, original_client_socket_id: … }后端对new_name有强校验在 src/backend/controllers/fs/FSController.ts 的renameEntry处理逻辑中若body.new_name不是字符串会直接抛出HttpError(400, Missing \new_name)。对应的测试用例也覆盖了这一行为见 [FSController.test.ts](https://link.gitcode.com/i/e886f393563186550bfc7850f1b6f875) 中FSController.renameEntry 描述块对缺少 new_name 抛出 400的断言。四、相对路径解析规则理解应用根目录官方文档说明如果path不是绝对路径它将被解析为相对于应用根目录的路径。在 puter-js 中这一规则由 utils/getAbsolutePathForApp.js 统一实现它对所有 fs 操作rename、write、mkdir 等生效具体逻辑如下GUI 环境的空路径保持原样若puter.env gui运行在 Puter 桌面 GUI 内且传入值为假falsy直接原样返回以保留旧行为。看起来像 UUID 的路径直接放行路径形如xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx正则/^[0-9a-f]{8}(-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i时被当作 UID 处理原样返回。空路径默认指向当前目录未提供路径时回退为.。以/或~开头的路径视为绝对路径不追加前缀。其余情况视为相对路径若存在puter.appID在某个 App 的上下文中调用则拼成~/AppData/{appID}/{relativePath}即该应用私有的数据目录否则拼成~/{relativePath}即用户主目录。这解释了为何在文档示例中直接传入hello.txt即可在 App 自己的存储空间内完成读写与重命名——SDK 会自动把它映射到正确的绝对位置。五、返回值puter.fs.rename()返回一个 Promise成功时 resolve 为被重命名文件或目录对应的FSItem对象。FSItem 是 Puter 文件系统中表示一个文件或一个目录的标准对象主要包含以下属性完整定义见 Objects/fsitem.md属性类型说明idstring条目创建时由 Puter 生成的唯一标识符。namestring条目的名称。重命名后此处即为新名称。pathstring条目相对于文件系统根目录的路径。isDirboolean是否为目录。createdinteger创建时间的 Unix 时间戳。modifiedinteger最近修改时间的 Unix 时间戳。accessedinteger最近访问时间的 Unix 时间戳。sizeinteger字节大小若为目录则为null。is_sharedboolean | null是否已共享条目不属于你时返回null。在浏览器端FSItem 还带有可直接使用的实例方法例如item.read()读取文件内容可参考 SDK 中的 FSItem.js。在后端响应链上控制器会调用this.#toClientEntry(renamed)将内部存储记录转换为客户端条目结构后再返回见 FSController.ts。六、完整示例示例一重命名一个文件官方文档场景以下 HTML 页面先在应用空间内创建hello.txt再将其重命名为hello-world.txt并把过程输出到页面html body script srchttps://js.puter.com/v2//script script (async () { // 先创建 hello.txt await puter.fs.write(hello.txt, Hello, world!); puter.print(hello.txt createdbr); // 将 hello.txt 重命名为 hello-world.txt await puter.fs.rename(hello.txt, hello-world.txt) puter.print(hello.txt renamed to hello-world.txtbr); })(); /script /body /html说明浏览器端需先通过script srchttps://js.puter.com/v2//script引入 puter.jsputer.print是示例页输出辅助方法。若在已登录的网页环境使用而尚未认证SDK 会经由ensureAuthenticated自动触发认证见 operations/scaffold.js。示例二读取重命名结果并使用返回的 FSItem// Node.js 环境中通过 puter-js 使用需先完成登录/认证 const item await puter.fs.rename(hello.txt, hello-world.txt); console.log(item.name); // hello-world.txt console.log(item.path); // 重命名后的完整路径 console.log(item.isDir); // false console.log(item.size); // 文件字节数示例三使用 options 对象形式当只传一个 options 对象时path与newName都必须在对象中给出const item await puter.fs.rename({ path: /my-project/old-name.txt, newName: new-name.txt, });示例四重命名一个目录rename同样适用于目录返回的 FSItem 中isDir为trueawait puter.fs.mkdir(reports); // 先建目录 await puter.fs.rename(reports, archive); // 目录改名示例五用 UID 代替路径当你不确定条目的完整路径、但持有其 UID 时可直接用uid定位。SDK 会在请求体中发送uid字段构造逻辑见 operations/rename.js// 先从 stat 或 readdir 等操作拿到条目的 uid const entry await puter.fs.stat(/some/where/old.txt); await puter.fs.rename({ uid: entry.uid, // 以 uid 定位可省略 path newName: new.txt, });示例六位置参数 传统回调puter.fs.rename(a.txt, b.txt, (item) { console.log(renamed to, item.name); }, (err) { console.error(rename failed, err); });七、底层原理一次重命名的完整请求链路理解从调用到落盘的请求链有助于排查问题。结合仓库源码puter.fs.rename(hello.txt, x.txt)的完整链路如下参数归一化defineOperation根据位置参数表[path, newName]把调用归一化为 options 对象见 operations/rename.js 与 operations/scaffold.js 的parseOperationArgs。构造请求体request回调中组装new_name若提供了uid则发送uid否则把path交给getAbsolutePathForApp解析成绝对路径后发送path。发送请求fsRequest先经ensureAuthenticated确保已认证失败时 Promise 以Authentication failed.拒绝随后通过 XHR POST 到{APIOrigin}/renamebody 为 JSON。服务端处理后端控制器 FSController.ts 的Post(/rename)路由renameEntry读取body.new_name缺失即抛 400解析目标条目路径或 UID后调用文件系统服务执行重命名并通过this.#emitGuiItemUpdated(renamed)通知 GUI最后返回客户端格式的条目 JSON。结果返回与缓存同步Promise resolve 为 FSItem同时SDK 内部建立的 socket 会收到服务端广播的item.renamed事件触发puter._cache.flushall()清理本地缓存确保后续stat、readdir等读到最新数据事件监听见 FileSystem/index.js 中bindSocketEvents对item.renamed、item.removed、item.updated等的处理。值得注意的行为细节uid优先级高于path两者同时存在时以uid为准见 rename 操作实现中的 if/else 分支。new_name是硬性要求服务端直接以body.new_name是否字符串判断缺失或类型错误都会得到 400Missing \new_name。请确保传入了newName且 SDK 侧会正确映射为new_name。original_client_socket_id该字段用于告诉服务端本次变更的来源连接。结合 SDK 中item.removed/item.updated等事件统一执行flushall()的机制可以推断该字段的设计意图是让触发操作的那个客户端能够识别并跳过对自己操作的重复缓存刷新。改名不等于移动若需要同时把条目移动到另一个目录请使用movesource/destination参数而不是renamerename只提交new_name不会携带目标目录信息。八、典型应用场景文件整理工具为上传的文件批量追加时间戳、序号或规范化命名。App 数据目录内的资源管理在 Puter App 中维护~/AppData/{appID}下的私有文件配合write、mkdir、stat等操作参见 FS/write.md 与 FS/mkdir.md。另存为副本再改名流程先使用write创建内容再用rename赋予最终文件名。Node.js / Workers 中的后台任务在非浏览器环境同样调用puter.fs.rename(path, newName)只需确保环境已正确配置认证信息。九、小结puter.fs.rename()是一个接口设计紧凑的重命名 API支持(path, newName)与(options)两种写法可用path或uid定位条目非绝对路径会自动相对应用根目录解析返回 Promise 。配合源码可以看清它的完整行为SDK 侧由 operations/rename.js 组装new_name/uid/path请求体经 operations/scaffold.js 统一发送后端 FSController.ts 的/rename路由对缺失new_name返回 400成功后服务端广播item.renamed事件触发客户端缓存刷新。在实际使用中只需记住三个要点newName必须提供、相对路径会自动定位到应用目录、想同时换位置请用 move 而非 rename。【免费下载链接】puter The Internet Computer! Free, Open-Source, and Self-Hostable.项目地址: https://gitcode.com/GitHub_Trending/pu/puter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考