用GridFSBucket下载文件必须配对async/await，所有I/O方法均为异步，漏掉await会导致卡死或InvalidOperationException；必须使用async Task签名并全程保持异步链路，不可调用.Wait()或.Result以防死锁。
用 GridFSBucket 下载文件必须配对 async/await
新版驱动（4.0+）中 GridFSBucket 所有 I/O 方法全是异步的，没有同步重载。写 DownloadToStream 或 OpenDownloadStream 时漏掉 await，编译能过但运行会卡死或抛 InvalidOperationException: Operation is not valid due to the current state of the object。
常见错误写法：bucket.DownloadToStreamAsync(id, stream).Wait() —— 在 ASP.NET Core 请求线程里调用 .Wait() 或 .Result 极易引发死锁，尤其在 .NET 7 默认启用 SynchronizationContext 的 Web 场景下。
- 必须用
async Task方法签名，且全程保持 async 链路 -
DownloadToStreamAsync和OpenDownloadStreamAsync都返回Task，不可忽略返回值 - 若需同步上下文兼容（如旧测试框架），改用
ConfigureAwait(false)避免捕获上下文
连接字符串和数据库名不能和 GridFS 操作脱节
GridFSBucket 不接受独立连接字符串，它必须绑定到一个已初始化的 IMongoDatabase 实例。很多人直接 new 一个 GridFSBucket 并传入连接字符串，结果报错 System.ArgumentNullException: Value cannot be null. (Parameter 'database')。
正确链路是：MongoClient → GetDatabase("myfiles") → NewGridFSBucket()。其中数据库名（如 "myfiles"）决定了底层使用的 fs.files 和 fs.chunks 集合前缀；若数据库不存在，首次写入时自动创建，但读取时必须确保该库已存在且含有效 GridFS 数据。
- 不要复用其他业务数据库的
IMongoDatabase实例来建GridFSBucket，除非你明确要共用fs.*集合 - 如果下载时提示
FileNotFoundException或空流，先确认fs.files集合里是否存在对应_id的文档 - 使用 Robo 3T 或 Compass 查看
myfiles.fs.files，验证filename和_id是否匹配预期
下载时选 ObjectId 还是 filename？取决于你怎么存的
GridFSBucket 提供两种下载入口：DownloadToStreamAsync(ObjectId) 和 DownloadToStreamAsync(string filename)。二者行为不同：前者严格按 _id 查找，后者按 filename 字段查（且默认只返回最新版本）。若你上传时用了 UploadFromStreamAsync 但没指定 options，系统会自动生成 ObjectId，此时用文件名查可能因重名或大小写不一致失败。
- 推荐上传时显式保存返回的
ObjectId到业务表，后续下载直接传这个 ID，最可靠 - 若必须用文件名，注意
filename是区分大小写的，且 MongoDB 不强制唯一；多个同名文件共存时，DownloadToStreamAsync(filename)只取uploadDate最大的那个 - 想查所有同名文件？得手动用
database.GetCollection<bsondocument>("fs.files").Find(...)</bsondocument>过滤
流处理不当会导致内存爆炸或文件损坏
用 DownloadToStreamAsync 时传入的 Stream 必须可写、未关闭，且长度不限（比如 FileStream 或 MemoryStream）。常见坑是传入一个固定容量的 MemoryStream，而文件实际大于预设容量，结果抛 IOException: Stream was too long；或者用 Response.Body 但没设 Content-Length，导致前端接收截断。
- 大文件下载优先用
FileStream，避免全载入内存：using var fs = File.Create("out.pdf") - 若需返回 HTTP 响应，用
OpenDownloadStreamAsync获取GridFSDownloadStream，再用CopyToAsync(response.Body)流式转发 - 别忘了设置响应头：
context.Response.ContentType = "application/pdf"、context.Response.Headers.ContentDisposition = "attachment; filename=\"report.pdf\""
最容易被忽略的是：GridFS 文件元数据（比如 contentType）不会自动映射到 HTTP 响应头，必须手动从 GridFSFileInfo 中提取并写入；否则浏览器可能无法正确识别文件类型或触发下载。
