createDownloadStream已废弃，必须先findOne查出文件文档再用openDownloadStream(fileDoc._id)；直接传字符串或null._id会报错或返回空流，且需手动设置Content-Type和Content-Disposition响应头。
createDownloadStream 为什么返回空流或报错
调用 createDownloadStream 后没数据、流立刻结束，或者抛出 GridFSBucketReadStream is not a constructor，大概率是没正确拿到文件句柄——它不接受文件名字符串直接读，必须先通过 find 或 findOne 查到对应 _id 或完整文档，再传给 openDownloadStream（createDownloadStream 是旧版别名，已废弃，新版驱动只认 openDownloadStream）。
常见误用：
- 传了
"report.pdf"字符串进去，而不是一个有效的ObjectId或查询对象 - 用的是 MongoDB Node.js 驱动 v5+，但文档还按 v3 写法调用
bucket.createDownloadStream(...) - 文件根本不存在，
findOne返回null，却直接拿null._id去开流，触发TypeError: Cannot read property '_id' of null
如何安全获取文件并打开下载流
必须分两步：先查元数据，再开流。不能跳过查找直接“凭名字硬读”。
-
bucket.find({ filename: "data.json" })返回游标，要用toArray()或next()拿结果；更推荐findOne({ filename: "data.json" })，避免多匹配 - 查到结果后，检查
doc是否为真值，再调用bucket.openDownloadStream(doc._id) - 如果文件名含特殊字符（如空格、中文），确保
filename字段在存储时做了精确匹配，MongoDB 默认区分大小写且不自动 trim
示例片段：
const fileDoc = await bucket.findOne({ filename: "config.yaml" });
if (!fileDoc) throw new Error("File not found");
const stream = bucket.openDownloadStream(fileDoc._id);
stream.pipe(res); // 直接 pipe 到 HTTP response
流式传输时 Content-Type 和文件名怎么设
HTTP 响应头不会自动从 GridFS 元数据中提取，contentType 和 filename 存在 files 集合文档的 metadata 或顶层字段里，得手动读出来。
Zenlink - Node SDK for ZenHeart
下载
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
-
fileDoc.contentType是常用字段，但不是必填；如果没设，可能为undefined，需 fallback 到application/octet-stream -
Content-Disposition头要手动拼：attachment; filename="xxx"，注意用encodeURIComponent处理中文名，否则前端可能乱码 - 别依赖
fileDoc.length设Content-Length：GridFS 分块存储，总长虽可读，但流式响应下设了反而可能被中间件覆盖或引发 chunked 编码冲突
设置头示例：
res.setHeader("Content-Type", fileDoc.contentType || "application/octet-stream");
res.setHeader(
"Content-Disposition",
`attachment; filename="${encodeURIComponent(fileDoc.filename)}"`
);
大文件传输中断或内存暴涨怎么办
直接 stream.pipe(res) 看似简单，但在高并发或网络抖动时容易出问题：Node.js 默认 highWaterMark 是 16KB，小块频繁写可能拖慢响应；若没监听 error，底层 socket 错误会静默吞掉，导致前端卡在 loading。
- 务必监听流的
error事件，并在出错时显式res.destroy()，否则连接会 hang 住 - 对超大文件（>100MB），考虑加
{ highWaterMark: 64 * 1024 }提升单次读取量，减少事件循环压力 - 不要用
stream.on("data", ...)手动拼 Buffer——这会把整个文件读进内存，彻底失去“流式”意义 - 如果用 Express，确保没全局启用
app.use(express.raw())之类中间件，它们可能拦截或重写响应流
健壮写法：
const stream = bucket.openDownloadStream(fileDoc._id);
stream.on("error", (err) => {
console.error("GridFS stream error:", err);
res.destroy();
});
stream.pipe(res);
GridFS 的流本质是分块拉取，真正难控的是网络层和客户端接收节奏——服务端能做的，就是别丢错误、别卡死、别瞎设 header。其他环节得靠反向代理（如 Nginx）或客户端重试兜底。
