GridFS是MongoDB用来存储超大文件的规范，而mongofiles则是官方配套的命令行工具。有了它，即使一行代码都不写，也能通过几个简单命令完成文件的上传、下载、列出、搜索和删除，特别适合运维人员做批量迁移，或者开发者在联调阶段快速验证文件是否落库。本文将从GridFS的存储原理讲起，详细介绍mongofiles的各项命令用法与常见问题的规避方法。
一、先弄懂GridFS的存储原理
GridFS并不是一种新的存储引擎，而是MongoDB在集合之上定义的一套文件存取规范。当一个文件通过GridFS写入时，驱动会把它切成多个固定大小的块（默认每个chunk为255KB），每个块作为一条文档存入fs.chunks集合，而文件的元信息（文件名、大小、类型、MD5、上传时间、chunk数量等）则以一条文档的形式存入fs.files集合。读取时先查fs.files拿到文件的整体信息，再按n字段顺序从fs.chunks中把各个块拼接还原。
这种设计绕开了BSON文档16MB的大小限制，理论上可以存放任意大的文件。同时由于文件被分块，Range请求式的分段读取也变得可行，比如视频网站做拖拽播放时，只需读取指定序号的chunk即可。不过要注意，GridFS不具备事务性和原子性，写入到一半中断的文件可能留下不完整的数据，需要业务侧做校验或清理。
另外，fs.files默认在filename和uploadDate上建立了索引，fs.chunks则在files_id和n上有复合索引，这些索引保证了按文件名查找和按顺序取块的高效性。理解这两个集合的结构，是后面用好mongofiles的基础。
二、mongofiles常用命令详解
mongofiles一般随MongoDB数据库工具包一起发布，新版本中它被拆分到了mongodb-database-tools安装包里。安装完成后在命令行执行mongofiles --version能正常输出版本号，就说明环境就绪。下面通过实际例子演示五个核心子命令。
1. 上传文件：put与-l选项
最简单的上传方式是put，后面直接跟本地文件路径。mongofiles会以文件的 basename 作为GridFS中的文件名。如果想让数据库里的文件名与本地文件名不同，或者路径中包含特殊字符，可以配合-l选项显式指定本地文件：
# 连接本地库并上传文件，GridFS文件名默认为 test.zip mongofiles --host 127.0.0.1 --port 27017 -d myfiles put test.zip # 用 -l 指定本地路径，文件在GridFS中命名为 backup.tar.gz mongofiles -d myfiles put backup.tar.gz -l /data/backup/2024.tar.gz
注意put命令每次执行都会新增一条记录，同名文件不会覆盖，而是并存多个版本。如果业务上需要覆盖语义，得先删除旧文件再上传，或者在元数据中做版本标记。
2. 下载文件：get
# 按文件名下载到当前目录 mongofiles -d myfiles get test.zip # 认证连接远程库并下载 mongofiles --host mongodb.ippipp.com -u admin -p secret --authenticationDatabase admin -d myfiles get test.zip
get命令会在当前工作目录生成同名文件，如果目录下已有同名文件会被直接覆盖，批量下载时尤其要留意。认证场景下必须通过--authenticationDatabase指明用户所在的库，否则会报权限错误。
3. 列出与搜索文件：list和search
# 列出库中所有GridFS文件 mongofiles -d myfiles list # 按名称前缀模糊搜索 mongofiles -d myfiles search report
list的输出包含文件名、大小和_id，适合快速盘点库内文件。search支持前缀匹配，比如上面的例子会命中report-2023.pdf、report_final.docx等所有以report开头的文件。如果想做更复杂的条件查询，就需要写脚本调用驱动API了。
4. 删除文件：delete
# 按文件名删除，同名文件会全部删除 mongofiles -d myfiles delete test.zip
delete按文件名匹配删除，且无法只删其中某一个版本，这是它和驱动API相比的一个明显局限。生产环境操作前，建议先用list确认目标文件，避免误删。
三、进阶选项与实用技巧
除了基本子命令，mongofiles还提供了一批控制行为的参数，熟练运用能覆盖大部分运维场景。
第一是自定义集合前缀。默认使用fs前缀，即fs.files和fs.chunks。当同一个库中需要隔离多套文件时，可以用--prefix指定不同前缀，例如--prefix images会读写images.files和images.chunks，相当于逻辑上的命名空间划分。
第二是写入关注与超时。对副本集环境，可以通过--writeConcern保证数据落盘到多个节点后再返回，例如--writeConcern majority；网络不稳定时加上--connectTimeoutMS和--socketTimeoutMS能避免长时间挂起：
# 指定集合前缀和写入关注级别 mongofiles -d myfiles --prefix images --writeConcern majority put photo.jpg # URI方式连接分片集群 mongofiles --uri "mongodb://user:pass@host1:27017,host2:27017/myfiles?replicaSet=rs0" put bigdata.csv
第三是中文文件名与编码问题。在Windows的cmd或PowerShell中操作中文文件名时，可能因为控制台编码不是UTF-8导致文件名乱码，解决办法是先执行chcp 65001切换编码，或者改用-l选项配合ASCII文件名上传。Linux下一般没有此问题，但要注意文件名区分大小写。
最后需要明确mongofiles的边界：它是运维和调试工具，不适合嵌入业务流程。应用内的文件读写应使用各语言驱动的GridFS API（如Node.js的mongodb包、Java的GridFSBucket），它们支持流式读写、按_id精确操作和自定义元数据，而mongofiles更擅长批量导入导出、数据迁移前的抽样验证这类一次性任务。两者结合使用，才能把GridFS的能力充分发挥出来。
mongofilesGridFSMongoDB文件存储修改时间：2026-08-31 21:06:40