GridFS文件损坏主因是流未正确消费、响应头缺失或元数据错误：需校验fileDoc非空、\_id为ObjectId、手动设Content-Type/Content-Disposition、监听流与响应事件、查无文件时返回404。
文件损坏不是 GridFS 本身出错，而是下载流没正确消费、响应头缺失或元数据读取错误——最常见的是 openDownloadStream 返回空流却没检查，或者 pipe 前漏设 Content-Type 导致浏览器乱解码。
为什么 openDownloadStream 返回空流或损坏数据
根本原因是没拿到真实文件句柄就开流，或文件根本不存在却继续执行。新版驱动（v5+）不接受字符串 _id 或 null，直接传会导致静默失败或空流。
-
bucket.openDownloadStream(fileDoc._id)中的fileDoc是findOne结果，必须先判空；若findOne返回null，null._id会抛TypeError: Cannot read property '_id' of null，但有些代码里没 catch，流就挂了 - 传入非 ObjectId 类型（比如字符串
"60a1b2c3d4e5f67890123456"没转ObjectId）时，openDownloadStream不报错但返回空流，pipe后响应体为空 - 文件名含中文/空格时，
findOne({ filename: "报表.pdf" })必须确保数据库存的filename字段值完全一致（MongoDB 区分大小写、不 trim），否则查不到
Content-Type 和 Content-Disposition 必须手动设
GridFS 不自动从元数据注入响应头。PDF、图片等二进制文件一旦用默认 application/octet-stream 返回，浏览器可能触发下载而非内嵌预览，或用错误编码解析字节流，导致“损坏”假象。
- 从
fileDoc读contentType字段：fileDoc.contentType || 'application/octet-stream'；没存就 fallback 到基于扩展名的硬编码判断（如.pdf→application/pdf） -
Content-Disposition决定是inline（浏览器打开）还是attachment（强制下载）：用res.setHeader('Content-Disposition', 'inline; filename="' + encodeURIComponent(fileDoc.filename) + '"') - 别用
res.send()或res.json()处理流——它们会覆盖Content-Type并尝试序列化，直接破坏二进制
流式传输必须完整消费，不能只 pipe 就完事
openDownloadStream 返回的是可读流，但若下游（如 Express 的 res）提前断开、或没监听 error 事件，流会卡住、连接不释放，部分数据丢失，客户端收到截断文件。
- 必须监听
downloadStream的error事件：downloadStream.on('error', err => { console.error('GridFS stream error:', err); res.status(500).end(); }) - 必须监听
res的close或finish事件来清理资源（尤其并发高时）：res.on('close', () => downloadStream.destroy()) - 避免在
pipe后再调res.end()——pipe已自动处理结束；手动end()会导致响应体多出空字节，PDF 等格式校验失败
查不到文件时别返回空响应
很多代码写成 if (!fileDoc) return;，结果 HTTP 状态码是 200 但响应体为空，前端以为“下载成功”，实际打开报错。
- 明确返回 404：
if (!fileDoc) return res.status(404).send('File not found'); - 如果业务允许模糊匹配（如忽略后缀），应统一在
filename字段加索引：db.fs.files.createIndex({ filename: 1 })，避免查询全表扫描导致超时或返回错文件 - 调试时可用
console.log(fileDoc?.metadata, fileDoc?.length, fileDoc?.uploadDate)确认元数据是否完整，length为 0 表示文件为空，也得按 404 处理
真正容易被忽略的点是：错误处理必须覆盖流生命周期全程——从 findOne 到 openDownloadStream 到 pipe，任一环节出错都得中断并返回明确状态，而不是让流静默失败。否则用户看到的“损坏”，往往只是后端没告诉它“根本没东西”。
