1. 从零跑通 Node.js MongoDB 的第一个读写示例很多人学 Node.js 卡在第一步环境装好了代码敲完了node app.js一跑就报错要么连不上数据库要么回调里拿不到数据。这篇就按「能跑起来」的标准来写从装环境到写出第一条insertOne和find每一步都给可复制的命令和配置。适合刚接触 Node.js、想用 MongoDB 存点真实数据、又不想在环境配置上耗三天的人。核心检索词先摆出来Node.js MongoDB 学习路线本质是「用 JavaScript 写服务端 用文档型数据库存数据」的最小闭环。Node.js 负责跑 JS 代码、起 HTTP 服务MongoDB 负责把 JSON 一样的文档存进去、查出来。两者之间用官方驱动或 Mongoose 连接。你不需要先学完整个 Express 生态先把「连上库、写一条、读一条」跑通后面加路由、加模型都是在这个骨架上长出来的。我试过最省事的路径是这样本地装 Node.js LTS 版本用 MongoDB Atlas 免费集群或者本地mongod然后写一个db.js专门管连接再写一个app.js调它。这样连接逻辑和业务逻辑分开后面换环境只改.env一个文件。下面按这个顺序展开中间会穿插用 TaoToken 统一 Key 来管理多模型调用的部分——因为学到后面你大概率会想加个 AI 接口提前把 Key 管理方式定下来能少踩坑。先确认版本。Node.js 建议 18 以上MongoDB 驱动 6.x 对应 Node 18。命令行里跑node -v npm -v输出类似v20.11.0和10.2.4就对了。如果版本太低去 Node.js 官网下 LTS 包重装别用系统自带的旧版本后面fetch和 ESM 语法会报奇怪的错。MongoDB 两种选法本地装社区版或者用云端免费集群。本地装的好处是断网也能跑坏处是 Mac M 系列芯片要额外配 Rosetta 或者用 brew 装。云端的好处是连接串直接复制坏处是第一次要配 IP 白名单。初学者我建议先用云端免费档把注意力放在代码上等跑通了再折腾本地。建项目目录mkdir node-mongo-demo cd node-mongo-demo npm init -y npm install mongodb dotenvmongodb是官方驱动dotenv用来读.env文件。装完package.json里会有依赖记录。如果你后面想用 Mongoose 做模型校验再npm install mongoose但第一步先用原生驱动理解底层怎么连的。目录结构先定成这样node-mongo-demo/ ├── .env ├── db.js ├── app.js └── package.json.env里放连接串db.js导出连接函数app.js调用并执行读写。这个结构小但边界清楚后面加路由就再建routes/目录不会乱。2. TaoToken 统一 Key 的前置准备与多模型调用管理学到后面你一定会遇到这个问题想给项目加个 AI 总结功能结果 OpenAI 一个 Key、Claude 一个 Key、国内模型又一个 Key每个 Key 的额度和过期时间还不一样.env里堆了一串XXX_API_KEY换环境时漏复制一个就 401。TaoToken 解决的就是这个用一个统一 Key 走一个 API 通道背后切换不同模型代码里只认一个base_url和一个key。先说清楚它是什么。TaoToken 是一个模型调用通道管理服务官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。你在控制台里创建 Key拿到一个以sk-开头的字符串然后所有请求的base_url都指向它模型名按需填。这样你的 Node.js 项目里只需要维护一个环境变量不用为每个模型单独写一套请求逻辑。适合谁用三种情况一是学习阶段想同时试几个模型的效果不想注册一堆账号二是小项目里 AI 调用量不大但希望 Key 集中管理、方便轮换三是团队协作时不想把多个厂商的 Key 散落在各人电脑上。如果你只是单纯学 MongoDB 读写这一步可以先跳过等要加 AI 功能再回来配。前置准备就三件事。第一注册后进控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。第二把 Key 存进.env不要硬编码在代码里。第三确认你要调的模型 ID比如对话类、代码类各有对应名称填错模型名会报model not found。这里有个关键点TaoToken 的 Key 和 MongoDB 的连接串是两回事前者管模型调用后者管数据库。但它们在项目里可以共用一个.env文件用不同变量名区分。这样你部署时只传一个环境文件不用分两处配。如果你用的是 Claude Code 这类编码工具TaoToken 也提供对应的接入方式文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。里面会写清楚 Base URL 填什么、Key 填哪里、Model ID 怎么选。这三件套Base URL Key Model ID是任何模型接入的通用公式记住这个换任何工具都是填这三个字段。长期做编码和 Agent 的话可以看 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。它适合需要持续调用、不想每次手动换 Key 的场景。但初学阶段不用急着上先把基础读写跑通。回到项目本身。现在.env里先放 MongoDB 的连接串等加 AI 功能时再加 TaoToken 的 Key。这样分阶段不会一上来就被一堆配置淹没。3. 可复制的 .env 配置与 Mongoose 连接代码这一节给完整可复制的配置。先建.env文件内容如下# MongoDB 连接串云端集群把 user password cluster 换成自己的 MONGODB_URImongodbsrv://user:passwordcluster.mongodb.net/learn_db?retryWritestruewmajority # 本地 MongoDB 用这行注释掉上面那行 # MONGODB_URImongodb://127.0.0.1:27017/learn_db # TaoToken 统一 Key等加 AI 功能时填 TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODEL你的模型ID注意.env不要提交到 git建个.gitignore写上.env和node_modules。这是新手最容易漏的一步Key 泄露了很麻烦。然后写db.js用 Mongoose 管理连接。为什么用 Mongoose 而不是原生驱动因为 Mongoose 给你 Schema 校验、默认值、中间件写业务时少写很多判断。先装npm install mongoosedb.js内容const mongoose require(mongoose); require(dotenv).config(); const MONGODB_URI process.env.MONGODB_URI; if (!MONGODB_URI) { throw new Error(缺少 MONGODB_URI请检查 .env 文件); } async function connectDB() { try { await mongoose.connect(MONGODB_URI, { serverSelectionTimeoutMS: 5000, }); console.log(MongoDB 连接成功); } catch (err) { console.error(MongoDB 连接失败:, err.message); process.exit(1); } } module.exports { connectDB, mongoose };这里serverSelectionTimeoutMS: 5000是关键。默认超时是 30 秒连不上时你要等半分钟才看到报错调成 5 秒能快速发现问题。踩过的坑云端集群如果 IP 白名单没加你的当前 IP就会一直卡在连接阶段5 秒超时能让你立刻意识到是网络层问题而不是代码问题。再定义一个数据模型建models/User.jsconst { mongoose } require(../db); const userSchema new mongoose.Schema({ name: { type: String, required: true }, email: { type: String, required: true, unique: true }, age: { type: Number, default: 0 }, createdAt: { type: Date, default: Date.now }, }); module.exports mongoose.model(User, userSchema);unique: true会在建索引时生效第一次插入重复 email 会报E11000 duplicate key error这是正常的唯一约束不是 bug。现在写app.js把读写跑起来const { connectDB } require(./db); const User require(./models/User); async function main() { await connectDB(); // 写入一条 const created await User.create({ name: 张三, email: zhangsanexample.com, age: 24, }); console.log(写入成功ID:, created._id.toString()); // 查询 const found await User.find({ name: 张三 }).lean(); console.log(查询结果:, JSON.stringify(found, null, 2)); // 更新 await User.updateOne({ name: 张三 }, { $set: { age: 25 } }); const updated await User.findOne({ name: 张三 }).lean(); console.log(更新后年龄:, updated.age); // 删除 await User.deleteOne({ email: zhangsanexample.com }); console.log(删除完成); process.exit(0); } main().catch((err) { console.error(运行出错:, err); process.exit(1); });跑之前确认.env里的连接串是对的。云端集群的密码里如果有特殊字符要做 URL 编码比如写成%40。这是高频错误报错信息通常是Invalid URL或者认证失败。运行node app.js预期输出MongoDB 连接成功 写入成功ID: 65f3a... 查询结果: [ { _id: 65f3a..., name: 张三, email: zhangsanexample.com, age: 24, ... } ] 更新后年龄: 25 删除完成看到这四行说明你的 Node.js MongoDB 闭环通了。后面加 Express 路由、加 AI 调用都是在这个基础上扩展。4. 验证请求与成功结果从数据库到模型调用数据库读写跑通后下一步是验证「外部请求」能不能成功。这里分两层一层是 HTTP 服务能不能响应一层是模型调用能不能返回。先加个最小的 Express 服务把数据库查询暴露成接口。装 Expressnpm install express改app.js为服务模式const express require(express); const { connectDB } require(./db); const User require(./models/User); const app express(); app.use(express.json()); app.get(/users, async (req, res) { try { const users await User.find().lean(); res.json({ ok: true, data: users }); } catch (err) { res.status(500).json({ ok: false, error: err.message }); } }); app.post(/users, async (req, res) { try { const user await User.create(req.body); res.status(201).json({ ok: true, data: user }); } catch (err) { res.status(400).json({ ok: false, error: err.message }); } }); async function start() { await connectDB(); app.listen(3000, () console.log(服务已启动: http://localhost:3000)); } start();启动后另开一个终端测curl -X POST http://localhost:3000/users \ -H Content-Type: application/json \ -d {name:李四,email:lisiexample.com,age:30}预期返回{ok:true,data:{name:李四,email:lisiexample.com,age:30,_id:...,createdAt:...}}再查curl http://localhost:3000/users能看到刚插入的李四说明 HTTP MongoDB 链路通了。现在验证模型调用。在项目里加一个ai.js用 TaoToken 的统一 Key 发请求。Node 18 自带fetch不用装 axiosrequire(dotenv).config(); const BASE_URL process.env.TAOTOKEN_BASE_URL; const API_KEY process.env.TAOTOKEN_API_KEY; const MODEL process.env.TAOTOKEN_MODEL; async function chat(prompt) { const res await fetch(${BASE_URL}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${API_KEY}, }, body: JSON.stringify({ model: MODEL, messages: [{ role: user, content: prompt }], }), }); if (!res.ok) { const text await res.text(); throw new Error(请求失败 ${res.status}: ${text}); } const data await res.json(); return data.choices[0].message.content; } chat(用一句话解释 MongoDB 的文档模型).then(console.log).catch(console.error);跑node ai.js如果返回一句解释说明 TaoToken 通道也通了。这里三个变量缺一不可BASE_URL指向 https://taotoken.net/api API_KEY是控制台创建的 KeyMODEL是你要调的模型 ID。任何一个填错报错信息会直接告诉你哪一层出了问题。验证模型是否可用也可以直接在模型对话页面测地址是 https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。在网页里选模型、输入问题能返回就说明 Key 和通道没问题再回到代码里排查就是纯代码问题了。成功的结果长这样数据库里有数据接口能查到模型能返回文本。三层都通你的学习环境就算搭完了。5. 本篇常见报错排查401、连接超时与 choices 读取失败这一节按真实报错来。你跑上面代码时大概率会遇到下面几个逐个说清楚原因和解法。报错一MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017这是本地 MongoDB 没启动。如果你.env里用的是mongodb://127.0.0.1:27017但本机没装或没起mongod就会拒绝连接。解法要么启动本地服务Mac 用brew services start mongodb-communityLinux 用sudo systemctl start mongod要么换成云端连接串。别在这卡着先用云端把代码跑通。报错二MongoServerError: bad auth : Authentication failed连接串里的用户名或密码错了。云端集群创建用户时设的密码如果含、#、%这些字符必须 URL 编码。比如密码ab123要写成ab%40123。另外确认数据库用户有对应库的读写权限只读用户插入会报not authorized。报错三401 Unauthorized或invalid api key这是 TaoToken 调用时的报错。原因通常是三个Key 没填、Key 复制时带了空格、Key 已失效。检查.env里TAOTOKEN_API_KEY是不是以sk-开头前后有没有引号或空格。dotenv读进来的值不会自动 trim多一个空格就 401。可以在代码里打印API_KEY.length确认长度对不对。报错四TypeError: Cannot read properties of undefined (reading choices)这个报错说明data.choices是 undefined也就是返回结构和你预期的不一样。常见原因是请求根本没成功但代码没检查res.ok就直接res.json()拿到的可能是错误对象。解法先判断res.ok不 ok 就把res.text()打出来看真实错误。另一个原因是模型名填错服务端返回了错误信息而不是正常的 choices 数组。记住任何读choices[0]之前先确认请求状态码是 200。报错五local proxy failed或连接被重置这类报错通常出现在网络层说明请求没到达目标地址。检查BASE_URL是不是写成了https://taotoken.net/api有没有多写或少写路径。另外确认本机没有奇怪的网络配置干扰。如果公司网络有限制换个人网络环境试。报错六E11000 duplicate key error collection这是 MongoDB 唯一索引冲突不是 bug。你重复插入了相同email的记录。解法插入前先findOne查一下或者用updateOne配合upsert: true。学习阶段直接换个 email 再插就行。报错七OAuth相关错误如果你用 Claude Code 或其他工具接入时看到 OAuth 报错说明认证方式选错了。TaoToken 的接入用的是 API Key 方式不是 OAuth 流程。在工具的配置里找 API Key 或 Base URL 的填写项把三件套填进去Base URL 填 https://taotoken.net/api Key 填sk-开头的字符串Model ID 填你要用的模型。文档里有各工具的具体截图地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。排查通用思路先看报错发生在哪一层。数据库层报错关键词是Mongo、ECONNREFUSED、authHTTP 层是401、404、500模型层是choices、model not found、rate limit。定位到层再对照上面的条目改配置比盲目改代码快得多。6. 把 Key 和连接串管好后面加功能才不慌跑通之后建议做两件小事。第一把.env.example提交到仓库里面只写变量名不写真实值别人克隆下来知道要配哪些。第二把db.js里的连接逻辑封装成可复用函数后面加测试或换库时只改一处。如果你要继续深入路线大概是这样先加 Express 路由分层routes/、controllers/再学 Mongoose 的 populate 做关联查询然后加错误处理中间件统一返回格式。AI 调用这块等业务需要时再引入用 TaoToken 的统一 Key 管理多模型避免 Key 散落。需要看模型列表和额度去控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 要创建新 Key去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite 。最后给一个实用技巧在app.js启动时打印一行环境摘要但不要打印 Key 的完整值只打印前 6 位和后 4 位。这样部署到新环境时一眼就能看出 Key 有没有配对又不会泄露。数据库连接串同理只打印主机名不打印密码。这个习惯能帮你在多环境切换时省很多排查时间。
