gridfs 不支持 rename() 方法，重命名只需更新 files 集合中对应文档的 filename 字段；必须确保 bucket 名和 _id 一致，chunks 集合无需改动；若需跨 bucket 或改 _id，则须读取、写入、删除并用事务保障一致性。
GridFS 没有 rename() 方法，别白找
MongoDB 官方 GridFS API（无论 pymongo、mongo-go-driver 还是 Node.js 的 mongodb 包）都不提供直接重命名文件的函数。这不是你漏看了文档，是它真没有。GridFS 本质是把文件拆成 chunks 和 files 两个集合存，元数据只在 files 文档里，改名 = 改那个文档的 filename 字段，但得自己确保不破坏关联。
用 update_one 更新 files 集合的 filename 字段
这是最轻量、最常用的做法，适用于大多数场景：文件内容不变，只改逻辑名称。关键不是“移动”，而是“标记为新名字”。
- 必须同时满足：
bucket名一致（默认fs）、_id或其他唯一字段能准确定位原文件（推荐用_id，避免同名冲突） - 只更新
files集合，chunks集合完全不动 —— 它们靠files_id关联，不依赖filename - 注意：如果应用层靠
filename做唯一查找（比如用find({"filename": "old.jpg"})），改完后旧查询就失效了
以 PyMongo 为例：
db.fs.files.update_one(
{"_id": old_file_id},
{"$set": {"filename": "new-name.pdf"}}
)
rename() 被误用时的典型报错和陷阱
搜到某些博客写 bucket.rename() 或 gridfs.rename()，基本都过时或混淆了驱动版本。真实常见错误包括：
-
AttributeError: 'GridFSBucket' object has no attribute 'rename'——pymongo >= 4.0已移除该方法 - 手动调
rename命令到fs.files集合：MongoDB 不支持对非system.*集合执行renameCollection，会报CommandNotSupportedOnView - 并发修改风险：如果两个请求同时改同一个
filename，可能覆盖彼此，建议加upsert=False和检查返回的matched_count
需要真正“移动”文件时（比如换 bucket 或改 _id）
这已经超出“重命名”范畴，属于迁移。必须读出原始数据、写入新条目、再删旧条目。性能差、有中间态风险，仅当业务强依赖 _id 或 bucket 隔离时才做。
- 不能跳过读取：GridFS 不支持服务器端 copy，
copyTo类方法在现代驱动里基本废弃 - 务必用事务（如果 MongoDB 版本 ≥ 4.0 且用 replica set）包裹“写新 + 删旧”，否则可能丢失文件
- 注意内存：大文件流式处理，别一次性
read()进内存；用download_to_stream+upload_from_stream
简言之：95% 的“改名”需求，改 files.filename 就够了；剩下 5%，得接受多一次 IO 和事务开销。
最容易被忽略的是：应用缓存、CDN URL、前端已保存的下载链接，全都不随数据库字段更新自动失效。名字改了，外部引用还在指向旧路径。
