根本原因是mongofiles不自动读取认证数据库和副本集配置，必须显式指定--authenticationDatabase（如admin）及--host rs0/节点列表格式，且仅操作默认fs bucket、不支持自定义bucket和部分URI参数。
mongofiles 报错 “connection refused” 或 “authentication failed”
根本原因不是 mongofiles 本身坏了，而是它默认不读取连接字符串里的认证数据库或 replicaSet 配置。mongofiles 是一个独立 CLI 工具，不走 Node.js 驱动那一套，它对连接参数极其敏感。
常见错误现象：mongofiles --host localhost:27017 --username admin --password 123 list 报 Failed: error connecting to db server: server returned error on SASL authentication step: Authentication failed.，但同样账号密码用 mongosh 能正常登录。
- 必须显式指定
--authenticationDatabase，比如admin或你建用户的那个库，否则它默认去test库鉴权（99% 失败） - 如果 MongoDB 启用了副本集，
--host不能只写一个节点，得用--host rs0/localhost:27017,localhost:27018,localhost:27019格式，否则连不上主节点 - URI 形式支持有限：虽然可以写
mongodb://admin:123@localhost:27017/?authSource=admin，但mongofiles对 query 参数解析很弱，replicaSet、ssl、tls等几乎全被忽略，老老实实用--host+--authenticationDatabase最稳
mongofiles 提示 “no such file or directory” 或空响应
这不是文件路径问题，是它默认操作的 GridFS bucket 名叫 fs，但你用 GridFSBucket 初始化时改了 bucketName（比如设成 uploads），mongofiles 就完全看不见那些文件——它压根不认自定义 bucket。
使用场景：你用 Node.js 写了 new GridFSBucket(db, { bucketName: 'uploads' }) 上传的文件，mongofiles list 查不到，mongofiles put 传进去的文件却出现在 fs.files 里，和你的应用代码完全隔离。
-
mongofiles固定操作fs前缀的集合（即fs.files和fs.chunks），不支持--bucket或类似参数 - 若必须用自定义 bucket，就别依赖
mongofiles管理，改用驱动 API 或直接查db.uploads.files.find()（注意集合名是{bucketName}.files） - 临时调试想让 mongofiles 和应用共用 bucket？初始化
GridFSBucket时显式传{ bucketName: 'fs' }，别依赖默认值
mongofiles 上传后 find() 查不到文件
不是数据丢了，是 mongofiles put 默认不写 contentType、metadata 等字段，而你的应用代码可能在 find() 里加了 { contentType: { $exists: true } } 这类条件，结果过滤掉了所有 mongofiles 传的文件。
性能影响：mongofiles 写入的文档 schema 和驱动 API 写入的略有差异，比如它不会自动加 uploadDate 的毫秒级时间戳（驱动会），也不会存 chunkSizeBytes（驱动默认 255KB，mongofiles 固定用这个但不显式写进元数据）。
- 检查元数据一致性：运行
mongofiles list -v（加-v输出详细信息），对比db.fs.files.findOne()返回的完整文档，看缺失哪些字段 - 避免混合使用：生产环境别一边用
mongofiles批量灌测试文件，一边用驱动做业务上传，元数据字段不统一会导致查询逻辑混乱 - 真正要验证文件是否存在，别只查
files集合，顺手看看chunks里对应files_id的文档数量是否匹配——mongofiles有时因网络中断只写了一半 chunk，files有记录但chunks缺失，文件实际不可读
为什么 mongofiles 不支持 TLS/SSL 连接？
它支持，但非常容易配错。mongofiles 从 v4.4 开始才真正稳定支持 --tls，且必须同时满足三个条件，缺一不可。
- 必须加
--tls，不能只写--ssl（旧参数已弃用，写了也不生效） - 必须指定
--tlsCAFile <path></path>，即使你用的是公共 CA 签发的证书，mongofiles 也不走系统信任链，不设就报unable to verify the first certificate - 如果 MongoDB 启用了
tlsMode: requireTLS，你还得确保--host用的是 DNS 可解析的域名（不是localhost或 IP），否则证书 CN/SAN 校验失败，连接直接断开
最容易被忽略的是：mongofiles 的 TLS 错误提示极其简陋，往往只报 connection reset by peer，根本看不出是证书问题。真遇到连不上，先关掉 TLS 测试通不通，再逐步加回 --tls 和 --tlsCAFile。
