Flutter无法直连MongoDB GridFS，因缺乏官方Dart驱动支持、沙盒环境限制及CORS阻止，需通过后端REST接口中转；最小接口为上传、下载、元信息查询三个端点，且必须基于ObjectId鉴权访问。
Flutter 本身不能直连 MongoDB GridFS，必须通过后端暴露 RESTful 接口中转。直接在客户端用 MongoClient 或尝试调用 GridFS 原生命令会触发跨域、认证、驱动不兼容（Dart 没有官方 GridFS 驱动）等硬性失败。
为什么不能在 Flutter 里直接读 GridFS？
Flutter 运行在沙盒环境，没有 MongoDB 官方 Dart 驱动支持 GridFS；mongo_dart 库仅支持基础 CRUD，不提供 GridFSBucket、openDownloadStream 等能力；且浏览器/移动端无法绕过 CORS 向 MongoDB 直连（即使开 mongod --bind_ip 0.0.0.0 也不行）。
常见错误现象：Failed to load resource: net::ERR_CONNECTION_REFUSED（直连 mongod）、Unsupported operation: Platform._operatingSystem（dart:io 在 Web 端不可用）、No such method 'openUploadStream'（驱动缺失）。
后端该暴露哪些最小接口？
只需三个端点，覆盖上传、下载、元信息查询，避免暴露 fs.files/fs.chunks 底层集合：
-
POST /api/gridfs/upload：接收multipart/form-data，用服务端驱动（如 Node.js 的mongodb包或 Spring Boot 的GridFsTemplate）存入 GridFS，返回{ fileId: "60a1b2c3..." } -
GET /api/gridfs/file/:fileId：根据_id查文件，响应头设Content-Type和Content-Disposition，流式返回二进制（不加载全量到内存） -
GET /api/gridfs/info/:fileId：返回 JSON 元数据，含filename、length、uploadDate、metadata字段，供 Flutter 展示文件名/大小/时间
不要暴露 filename 查询接口（如 /file?name=xxx），因 GridFS 的 filename 字段非唯一、易编码错、不支持模糊匹配；一律用 _id（BSON ObjectId）作为主键传参。
Flutter 端如何安全发起请求？
使用 http 包，注意三点：
- 上传大文件时，用
http.MultipartFile.fromPath()而非fromBytes()，避免 OOM；设置超时：http.Request request = http.Request('POST', uri)..headers['Authorization'] = 'Bearer $token'; - 下载时别用
http.get().then((r) => r.body)——这会把整个文件载入内存；改用http.Client().send(request).then((response) => response.stream)获取Stream<list>></list>，配合File.openWrite()分块落盘 - 所有接口必须带鉴权头，例如
Authorization: Bearer <jwt></jwt>；后端需校验该 token 是否有权访问对应fileId（防止越权下载）
示例下载片段（省略异常处理）：
final file = File('/path/to/save.pdf');
final sink = file.openWrite();
final req = http.Request('GET', Uri.parse('https://api.example.com/api/gridfs/file/$fileId'));
req.headers['Authorization'] = 'Bearer $token';
final resp = await http.Client().send(req);
await for (final data in resp.stream) {
await sink.add(data);
}
await sink.close();
容易被忽略的坑：文件名中文、分块缓冲、权限粒度
后端存储时，若上传字段含中文 filename，Node.js 驱动默认按 UTF-8 解析，但某些前端 form 表单可能用 ISO-8859-1 编码，导致查不到文件；Spring Boot 中 GridFsTemplate.store() 若未显式指定 filename 字符集，也会乱码。
Flutter 下载大文件时，resp.stream 默认 chunk 是 64KB，但若后端 Nginx 或 API 网关设置了 proxy_buffer_size 4k，会导致流被截断；应在网关层调大缓冲或改用 Transfer-Encoding: chunked 响应。
权限不能只校验“用户已登录”，必须校验“该 fileId 归属当前用户”——GridFS 本身无 RBAC，靠后端在 files 集合的 metadata 字段存 {"ownerId": "user_abc"}，查询前先做 find({ _id: fileId, "metadata.ownerId": userId })。
