gridfs 中文文件名乱码的根本原因是传入的 filename 值本身不是合法 utf-8 字符串，而非 mongodb 不支持中文；常见错误包括未正确解码 gbk 字节流、http 未解码、java 错误指定字符集、node.js 未显式指定编码及未统一 nfc 标准化。
GridFS 本身不处理 URI 编码，filename 字段必须是合法 UTF-8 字符串；所谓“URI 编码”是 HTTP 层或前端传参时的转义行为，不是 GridFS 的写入要求——真正出问题的地方，是字符串在进入 fs.put() 或 uploadFromStream() 前，已经因平台/路径读取/HTTP 解码不当而损坏。
为什么中文文件名在 GridFS 中显示为 或乱码
根本原因不是 MongoDB 存不了中文，而是你传给 GridFS 的 filename 值本身不是 Unicode 字符串。常见场景包括：
- Windows 上用
os.listdir()或sys.argv获取含中文的路径后，未以 UTF-8 解码（实际是 GBK 字节流），直接拼进filename - Web 请求中，前端用
encodeURIComponent()编码文件名，后端没调用decodeURIComponent()就直接当 filename 使用 - Java 中用
new String(bytes, "GBK")构造字符串，但后续未标准化为 NFC 形式，导致某些字符（如带声调的汉字）被拆分为多码点，跨平台读取时顺序错乱
Python PyMongo：filename 必须是 str，不能是 bytes
PyMongo 会把 Python str 自动 encode 成 UTF-8 存入 files.filename；一旦你传 bytes，它就原样存进 BSON，读取时按 UTF-8 解码必然失败。
- ✅ 正确：
fs.put(f, filename="发票_2026年5月.pdf")（Python 3 中字面量默认是str） - ❌ 错误：
fs.put(f, filename=b'\xb7\xa2\xc6\xb1.pdf')（这是 GBK 编码的 bytes，不是合法 UTF-8） - ⚠️ 高危：
filename = path.encode('gbk').decode('utf-8')（强行 decode 会抛UnicodeDecodeError或静默替换为 ）
Java Spring Boot：避免 String 构造时指定错误 charset
Spring Boot 的 GridFSBucket.uploadFromStream() 接收 String 类型 filename，但很多开发者从 HTTP header 或 multipart 参数中取值时，忽略了原始字节流的编码来源。
- 如果前端用
Content-Disposition: attachment; filename*=UTF-8''%E5%8F%91%E7%A5%A8.pdf，Java 应用需用MimeUtility.decodeText()或手动解析filename*，而不是直接取filename字段 - 不要写：
new String(filenameBytes, "GBK")—— 改用StandardCharsets.UTF_8，并确保前端确实发的是 UTF-8 编码 - 建议统一做 NFC 标准化：
Normalizer.normalize(filename, Normalizer.Form.NFC)，防止“广”和“廣”这类等价但码点不同的写法引发查询失败
Node.js：Buffer → string 转换必须显式指定 encoding
Node.js 的 fs.readFile() 或 req.file.originalname 返回的可能是 Buffer 或已解码的 string，但 Express multer 默认对 originalname 做了 UTF-8 解码——前提是客户端请求头声明了 charset=utf-8。
- 安全做法：始终用
iconv-lite显式转换（尤其处理 Windows 客户端上传）：iconv.decode(buffer, 'gbk') - 上传前校验：
Buffer.from(filename, 'utf8').toString('utf8') === filename，若为false，说明输入不是合法 UTF-8 - 避免直接拼接：
`${dir}/${req.file.originalname}`—— 若originalname是乱码，整个路径就废了
最易被忽略的一点：GridFS 查询时用 find({ filename: "测试.txt" })，看似简单，但如果写入时用了 NFC，查询却用 NFD，就匹配不上。统一做 Normalizer.normalize(..., NFC) 不是可选项，是必要步骤。
