插件连不上八成因本地未运行mongod或连接字符串格式错误；需检查mongod进程、端口27017、协议头mongodb://、密码URL编码及权限配置。
装完插件连不上，八成不是插件问题，而是本地没跑 mongod 或连接字符串格式错了一处——比如漏了 mongodb:// 前缀、密码没 URL 编码、端口写成 27018 却没改配置。
为什么点 Connect 一直转圈或报 Connection refused
插件本身不带数据库服务，它只是个图形化客户端。你必须先确保有真实运行的 mongod 实例。
- macOS/Linux 执行
ps aux | grep mongod，看进程是否存在；Windows 就查任务管理器里有没有mongod.exe - 默认监听端口是
27017，如果改过（比如用--port 27018启动），连接字符串里就得显式写上:27018 - 本地连接字符串必须带协议头：
mongodb://localhost:27017，写成localhost:27017或127.0.0.1都会失败 - 如果用 Docker 启动，确认容器端口已映射：
-p 27017:27017，且容器内mongod正常运行（docker logs <container>看日志）
连接字符串怎么填才不被解析失败
插件对 URI 格式极其敏感，一个空格、一个未编码的特殊字符都会导致 Invalid connection string。
- 最简可用格式：
mongodb://localhost:27017（无认证、无数据库名） - 带用户名密码时，密码含
@、/、:必须 URL 编码，例如密码pa@ss/word要写成pa%40ss%2Fword - 指定默认数据库可加在末尾：
mongodb://localhost:27017/myapp，但不会影响连接权限校验 - 远程 Atlas 连接务必带
/?appName=VSCode后缀，否则部分集群会拒绝认证 - 不要手动敲空格——复制粘贴后检查前后有没有看不见的空白符
连上了却看不到集合或查不出数据
这通常不是连接失败，而是权限或视图配置导致“能连不能看”。
- 插件默认用连接字符串末尾的数据库名（如
myapp）做上下文，但认证可能发生在admin库；用户若没被授权访问myapp，集合列表就为空 - 用
mongosh连上去执行db.runCommand({connectionStatus: 1})，检查authInfo.authenticatedUsers和对应角色权限 - 集合名以
system.开头（如system.users）或纯数字开头（如123logs），插件默认隐藏，可右键连接节点点Refresh或手动在搜索框输集合名 - 查询语句必须是合法 BSON 对象：
{ "status": "active" }可行，{ status: "active" }（没引号）会报Unexpected token
为什么执行查询后返回乱码、字段缺失或超时
插件底层调用的是 Node.js Driver，它对 BSON 类型、响应大小和语法支持有明确限制，不是所有 shell 里能跑的都支持。
-
find()返回游标，不是结果集——插件的 “Run Query” 按钮会自动加.toArray()，但手写脚本里漏了就会卡住或返回空 - 聚合管道中别用
$expr嵌套太深，Driver 有默认 BSON 大小限制（16MB），大文档或复杂计算容易触发timeout - 字段值是
ObjectId、Date、BinData等类型时，插件会尝试转成 JSON 可读格式，但某些自定义类型可能显示为{"$oid": "..."}这类结构，属正常行为，不是数据损坏 - 如果启用了 TLS/SSL（比如 Atlas 默认开启），连接字符串里得加
?ssl=true，否则握手失败表现为超时
最容易被忽略的一点：插件依赖全局可执行的 mongosh，不是旧版 mongo。装错版本或 PATH 没配对，连接过程会在后台静默失败，只显示“Connecting…”不动。验证方式很简单：mongosh --version 能输出 v1.0+，且 VS Code 是从终端启动（而非桌面图标双击），才能保证环境变量生效。
