GridFS 存同名文件不会自动覆盖，而是新增不同 _id 的记录；需应用层通过先删后存或加唯一索引并捕获错误来实现覆盖。

GridFS 里存同名文件会覆盖吗

不会自动覆盖，但 put() 方法默认行为是「新增」，不是「更新」——也就是说，同名文件会被当成不同文件存进去，_id 不同、filename 相同，查出来就是多条记录。这不是 bug，是 GridFS 的设计逻辑：它不把 filename 当主键。

常见错误现象：find({ filename: "report.pdf" }) 返回多个文档，应用读取时随机拿到旧版本；或者用 get_last_version() 拿到的不是你刚传的那个。

• filename 字段只是元数据，不唯一，也不索引（除非你手动加）
• 真正区分文件的是 _id（ObjectId），每个 put() 都生成新 _id
• 如果你依赖文件名做查找，必须自己控制版本或去重逻辑

怎么安全地实现“同名即覆盖”

GridFS 本身没提供原子性的「upsert by filename」，得靠应用层组合操作：先删再存，或先查再决定是否跳过。关键在「删」这步不能漏掉旧文件的 chunks。

使用场景：上传用户头像、日志归档、配置文件热更新——这些都需要确保名字唯一且最新生效。

• 别只删 fs.files 文档，必须调用 delete_one()（驱动里对应方法），它会连带清理 fs.chunks
• Python PyMongo 示例：

  gridfs_bucket.delete(file_id)  # file_id 来自 find_one({"filename": name})

• Node.js MongoDB Driver 示例：

  await bucket.delete(fileId); // fileId 是 ObjectId

• 并发上传时加一层 filename 锁（比如 Redis 分布式锁），否则可能删错或漏删

要不要给 filename 加唯一索引

可以加，但加了之后 put() 再存同名就会抛 DuplicateKeyError，不是静默失败——这对防御性编程有用，但也意味着你要主动捕获并处理这个错误。

性能影响很小，索引只在 fs.files 上，fs.chunks 不受影响；兼容性没问题，所有驱动都支持。

• 建索引命令：

  db.fs.files.createIndex({ filename: 1 }, { unique: true })

• 错误信息是：DuplicateKeyError: E11000 duplicate key error collection: mydb.fs.files index: filename_1 dup key: { filename: "config.json" }
• 加了索引后，就不能靠「先删后存」来覆盖了，得改成「捕获错误 → 删除旧 → 重试」流程
• 如果业务允许历史版本保留（比如审计需求），就别加这个索引

真正难搞的是“部分更新”和“大文件断点续传”

GridFS 没法改已存文件的内容，哪怕只改一个字节，也得整个重传。所谓“重名覆盖”，本质是删旧+存新，中间有空窗期——如果这时有服务正在读那个文件，可能读到 404 或旧版本。

容易被忽略的地方：chunk 大小默认 255KB，但如果你改过 chunkSizeBytes 参数，删旧文件时要确保用同一个 bucket 实例，否则 delete() 可能找不到关联的 chunks。

• 上传中途失败？GridFS 不保证事务，得靠客户端校验 MD5/SHA256 后再触发删除+重传
• 多个服务共用一个 bucket？删文件前建议加 uploadDate 时间范围判断，避免误删刚被其他服务上传的同名文件
• 别依赖 filename 做权限控制——它可被任意修改，应结合用户 ID、命名空间前缀等字段做隔离