GridFS 不强制校验文件名唯一性，同名文件可共存于 fs.files，需用 ObjectId 精准检索；业务需覆盖时应先删旧再传新，或采用改名策略（如加时间戳、SHA256哈希）；针对小文件，建议将 chunkSizeBytes 设为 4KB 以显著提升查询性能。
GridFS 默认不校验文件名唯一性，冲突需由应用层主动控制
首先需要明确一个关键概念：GridFS 本身并不限制同名文件的上传操作。这意味着，在 fs.files 集合中，完全可能出现多个 filename 字段值完全相同的文档记录。其直接后果是，如果仅通过 findOne({ filename: "report.pdf" }) 这类方式查询，返回的可能是任意一个匹配项，不一定是您期望的最新版本文件。
为何会如此设计？根本原因在于 GridFS 的核心设计目标是分块存储大文件，它并非一个完整的文件系统替代方案。因此，保障文件名唯一性的责任，被明确地交由上层应用逻辑来承担。
- 每次调用
uploadFromStream()方法都会生成一个全新的_id（默认为ObjectId类型），对应着一组独立的fs.files和fs.chunks集合记录。 filename字段仅作为元数据存储，默认情况下并未建立唯一索引（除非您手动创建）。- 因此，如果业务逻辑要求“同名文件上传即覆盖”，则必须由应用层显式地执行“先删除旧文件，再上传新文件”的操作。GridFS 本身不提供原子性的重命名或更新插入语义。
使用 ObjectId 检索最为可靠，但需注意其存储于 fs.files._id 而非文件内容中
那么，最可靠的 GridFS 文件检索依据是什么？答案是每个 GridFS 文件在 fs.files 集合中拥有的唯一 _id（通常为 ObjectId 类型）。文件的数据块存储在 fs.chunks 集合中，并通过 files_id 字段与该 _id 进行关联。这才是检索文件时真正可靠的唯一标识。
一个常见的认知误区是，试图从文件流或 buffer 数据中反向推导出 ObjectId —— 这是行不通的。ObjectId 仅在文件写入时由驱动程序生成并返回，应用程序必须自行妥善保存。
- 上传文件后，务必捕获并存储返回的
ObjectId：const { _id } = await bucket.uploadFromStream("photo.jpg", stream); // _id 是 ObjectId 实例 - 后续读取文件时，应使用
find({_id: _id})或openDownloadStream(_id)方法，切忌再将filename当作主键来查询。 - 如果选择以字符串形式存储
_id，查询时务必使用new ObjectId(str)将其转换回对象，否则会因 BSON 类型不匹配而导致查询失败。
如何按文件名查询又避免冲突？添加时间戳或哈希后缀是高效落地方案
如果前端界面或 API 接口必须支持“通过原始文件名下载”的功能，同时又需要避免文件被随机覆盖的风险，该如何处理？最直接且推荐的方案是在上传时主动对文件名进行改造，而非依赖后期创建索引或用事务来兜底。
尽管 MongoDB 5.0+ 版本支持多文档事务，但 GridFS 的 uploadFromStream 和 delete 操作无法被简单地包裹进同一个事务中（因其底层涉及两个集合的写入，且驱动程序未封装原子操作）。
- 安全做法：上传前为文件名拼接时间戳，例如
`${Date.now()}-${originalName}`，这样可以有效保证全局唯一性。 - 更优做法：计算文件内容的 SHA256 哈希值，采用
哈希值 + 扩展名的方式命名。此做法的优势在于，相同内容的文件只会存储一份，能有效节省存储空间并实现去重。 - 如果业务上必须保留原始文件名，可以额外建立一张映射表（记录
filename到最新_id的对应关系），每次上传后更新此表。但需注意，此方式需要应用层自行处理并发写入时的竞争条件。
切勿忽略 chunkSizeBytes 对文件检索性能的关键影响
此问题虽与文件名冲突无直接关联，但许多开发者在按 ObjectId 查询文件时发现延迟过高，最终排查原因往往是块大小（chunkSizeBytes）参数设置不合理。
GridFS 默认的 chunkSizeBytes 为 255KB。对于小文件（例如仅几 KB 的图标文件）而言，这会产生大量碎片化的数据块。查询时，系统需要聚合更多 fs.chunks 集合中的文档，导致 I/O 开销显著增加，影响查询速度。
- 若应用主要上传小文件，将
chunkSizeBytes设置为 4096（即 4KB）通常更为合适，可优化查询性能。 - 若主要上传大视频等媒体文件，则可将其提高至
1024 * 1024（即 1MB），以减少 chunk 文档的总数量，提升大文件存取效率。 - 需注意，修改块大小必须在新建
GridFSBucket实例时指定，此设置对已存在的历史文件不会产生任何影响。
在实际项目开发中，文件名冲突问题常在灰度发布或定时任务重新运行的场景下暴露——用户可能毫无感知，但后台日志中已堆满重复的 filename 记录，却无法检索到最新的文件版本。此时再回头寻找当初存储的 _id，往往发现早已丢失。因此，从项目初期就建立正确的文件检索策略与命名规范至关重要。
