GridFS操作必须通过mongo.Database.GridFSBucket()获取bucket实例，避免直接导入旧包或手动构造；上传需使用io.Reader并设置ChunkSizeBytes，下载应使用io.Copy进行流式传输防止内存溢出。

mongo-driver中已无独立的gridfs包

如果你仍在网上搜索如何导入Go语言的GridFS包，很可能已经使用了过时的教程。实际上，Go官方mongo-driver（自v1.10版本起）早已移除了独立的gridfs子包。那些旧教程中引用的go.mongodb.org/mongo-driver/mongo/gridfs路径，在v1.5版本之后就已经被废弃。如今，所有GridFS功能都已整合到go.mongodb.org/mongo-driver/x/mongo/driver/gridfs中——但请注意，这属于内部API，**开发者绝对不应直接导入**。

唯一正确的入口是：通过mongo.Database的GridFSBucket()方法来获取*gridfs.Bucket实例。

常见的错误通常表现为两种：编译时报错cannot find package "go.mongodb.org/mongo-driver/mongo/gridfs"，或者运行时提示undefined: gridfs.NewBucket。这些都指向同一个问题：使用了过时的导入路径，或者试图手动构造Bucket实例。

• 首先，确保驱动为最新版本：go get go.mongodb.org/mongo-driver/mongo@latest。
• 请牢记，GridFSBucket()是*mongo.Database的方法，并非独立的构造函数。
• 底层的x/mongo/driver/gridfs会被自动间接引入，开发者无需显式处理。

初始化Bucket需正确传入数据库和配置选项

GridFS的原理是将大文件分割成多个数据块，分别存储到fs.chunks和fs.files这两个集合中。因此，调用GridFSBucket()必须绑定一个明确的*mongo.Database对象，并且默认会使用"fs"作为集合名前缀。如果你的MongoDB服务端已经使用了自定义的集合名（例如"uploads.chunks"），则需要通过gridfs.Options来调整配置。

这里容易遇到的误区是：不设置BucketOptions就期望它能自动适配现有集合；或者误将Database对象当作Client传入，导致程序直接崩溃。

立即学习“go语言免费学习笔记（深入）”；

• 基础初始化：bucket := db.GridFSBucket() —— 这将使用默认的fs.files和fs.chunks集合。
• 自定义集合前缀：bucket := db.GridFSBucket(&gridfs.Options{BucketName: "uploads"}) → 对应的集合将变为uploads.files和uploads.chunks。
• 指定编码器：&gridfs.Options{Encoder: bson.NewEncoder(...)}，不过在绝大多数场景下，使用默认编码器就已足够。

上传文件不应直接传递*os.File，应使用io.Reader

bucket.UploadFromStream()方法的第二个参数明确要求是io.Reader类型，而非*os.File。虽然*os.File也实现了io.Reader接口，但直接传递它容易导致文件指针位置错乱（尤其是在多次调用时），并且你无法控制底层的缓冲区大小。

由此引发的典型问题包括：上传后文件内容为空、文件长度不匹配，或者在并发上传时出现read: connection reset by peer等连接错误。

• 安全做法：对于小文件，可以使用bytes.NewReader(data)；处理大文件时，更推荐使用bufio.NewReader(f)；如果是处理HTTP上传请求，直接传递http.Request.Body即可。
• 务必设置ChunkSize：通过gridfs.UploadOptions中的ChunkSizeBytes字段来设置分块大小（默认是255KB）。在上传GB级别的视频等大文件时，建议设置为1024 * 1024 * 4（即4MB），这样可以有效减少chunk文档的数量，提升存储与读取效率。
• 元数据存放位置：自定义的元数据应写入Options.Metadata字段（类型为bson.M），不要试图将它们塞进文件名中——文件名仅参与_id的生成逻辑。

下载大文件必须使用DownloadToStream流式传输，避免内存耗尽

bucket.DownloadByID()会返回一个*gridfs.File，它确实实现了io.ReadCloser接口，但**绝对不要直接对它调用io.ReadAll()**。一旦文件超过100MB，进程的内存占用就会急剧上升，甚至可能触发系统的OOM killer，直接终止你的服务进程。

设想一个真实场景：用户请求下载一个PDF文档或视频文件，后端需要做的是边从GridFS读取数据块，边向HTTP响应体中写入，而不是先将整个文件完全加载到内存中，再一次性输出。

• 正确方法：file, _ := bucket.DownloadByID(ctx, fileID); defer file.Close(); io.Copy(responseWriter, file)。利用io.Copy进行流式传输，这是保证性能与稳定性的关键。
• 需要校验MD5？：直接调用file.GetMD5()方法即可。此方法会从files集合的md5字段中直接读取预先计算好的值，而非重新计算，效率更高。
• 错误处理：当文件不存在时，DownloadByID返回的错误是mongo.ErrNoDocuments，而非简单的nil。请使用errors.Is(err, mongo.ErrNoDocuments)来进行精确判断。

最后需要提醒的是，GridFS并非适用于所有场景的万能存储方案。对于小文件（例如小于16MB），直接作为BSON文档存储在普通集合中，通常是更简单且性能更优的选择。