VSCode 不提供 MongoDB 服务，必须手动运行 mongod 进程；连接失败主因是 mongod 未启动或连接字符串格式错误（如缺协议、空格、特殊字符未编码），需用原生驱动验证连通性并确保插件与代码库名一致。
VSCode 本身不提供 Node.js 运行时或 MongoDB 服务，它只负责编辑和启动代码；真正连接 MongoDB 的是你的 Node.js 进程，而 mongod 必须独立运行。配置失败的主因几乎总是环境没就位，而非代码写错。
本地 mongod 进程必须真在跑
VSCode 插件或 Node.js 代码都无法“启动” MongoDB —— 它得你手动开。插件连不上、mongoose.connect() 超时、new MongoClient() 报 connect ECONNREFUSED，90% 是因为 mongod 根本没运行。
- macOS/Linux：终端执行
ps aux | grep mongod，看到带--dbpath和端口的进程才算活 - Windows：任务管理器搜
mongod.exe，确认状态为“正在运行” - 默认端口是
27017；改过就必须显式写进连接串，比如mongodb://localhost:27018 - Docker 启动时，检查是否映射了端口：
-p 27017:27017，且bindIp包含127.0.0.1
连接字符串格式必须严格合规
VSCode 插件和 Node.js 驱动都用标准 URL 解析器，空格、漏协议、特殊字符未编码都会直接解析失败，不是报错而是静默截断。
Zenlink - Node SDK for ZenHeart
下载
ZenHeart zenlink 与 zenlink-mcp 为 OpenClaw，涵盖安装、MCP 注册、钩子接线、入站轮询及升级维护。
- 必须带完整协议头：
mongodb://localhost:27017✅，localhost:27017❌ - 密码含
@、/、:等？必须 URL 编码：encodeURIComponent('pa@ss/word')→pa%40ss%2Fword - 连接串前后不能有空格：
mongodb://...或mongodb://...都会报Invalid connection string - 末尾加库名（如
mongodb://localhost:27017/myapp）只影响默认打开库，不影响连接本身
Node.js 项目里连 MongoDB 的最小可行写法
别一上来就写 Mongoose model，先用原生驱动验证通路。Mongoose 的 connect() 默认不抛错，容易误判成功。
- 装驱动：
npm install mongodb（不是mongoose，先排除 ODM 干扰） - 新建
test.js，内容如下：
const { MongoClient } = require('mongodb');
const url = 'mongodb://localhost:27017';
const client = new MongoClient(url);
async function run() {
try {
await client.connect(); // 这里才真正发起 TCP 连接
console.log('✅ 已连上 MongoDB');
const db = client.db('testdb');
const coll = db.collection('test');
await coll.insertOne({ hello: 'world' });
console.log('✅ 写入一条文档');
} catch (err) {
console.error('❌', err.message); // 看具体错误，不是堆栈
} finally {
await client.close();
}
}
run();
- 运行：
node test.js；成功输出两行 ✅ 才算通 - 如果卡住或报
ECONNREFUSED，回头检查mongod进程和端口
VSCode 插件和 Node.js 代码的上下文必须对齐
你用 mongoose.connect('mongodb://localhost:27017/app') 写进 users 集合，但插件连的是 mongodb://localhost:27017/admin，就永远看不到那条数据 —— 它们压根不在一个库。
- 插件连接串末尾的库名（如
/myapp）和 Node.js 里client.db('myapp')或mongoose.connect('.../myapp')必须一致 - 右键插件里的连接节点 → Refresh，强制重载集合列表（尤其当集合名是
system.开头或纯数字时，默认隐藏） - 查询语句必须是合法 BSON 对象：
{ "name": "Alice" }✅，{ name: "Alice" }❌（JS 字面量不被接受） - 认证用户需被授予目标库的
readWrite角色；用mongosh连上去执行db.runCommand({connectionStatus: 1})查权限
最常被忽略的点：你以为连上了，其实只是 mongoose.connect() 返回了一个 Promise，而没等它 resolve 就结束了进程；或者插件连的是 admin 库，但你的代码往 myapp 写，两边根本不在同一片空间里。
