1. 从一次搜索框需求说起Nodejs 模糊查询到底解决什么问题做后端接口时搜索框几乎是绕不开的功能。用户输入「苹果」你总不能要求数据库里存的商品名必须一字不差叫「苹果」才返回结果吧现实情况是商品可能叫「红富士苹果」「苹果手机壳」「进口苹果 5 斤装」这时候就需要模糊查询——按关键词做部分匹配而不是精确相等。在 Nodejs 技术栈里最常见的组合是 Express 负责路由和参数接收Mongoose 负责和 MongoDB 打交道。MongoDB 原生支持用正则做模糊匹配而 Mongoose 作为 ODM把这件事包装得更顺手。核心就一句话把用户传来的关键词拼成一个正则表达式塞进查询条件里。这篇文章面向的是正在写 Nodejs 后端接口、需要给列表页加搜索功能的开发者。不管你是做用户列表按昵称搜索还是商品列表按名称搜索思路都一样。我会把可复制的路由代码、Mongoose 查询写法、正则转义处理、Postman 验证步骤以及我实际踩过的报错都讲清楚。你跟着做基本能在一个现有 Express 项目里把模糊查询跑通。先明确几个关键点避免后面绕弯模糊查询的本质是$regex操作符配合RegExp对象使用i标志表示忽略大小写做搜索时几乎必加用户输入不能直接拼进正则特殊字符要转义否则会报错甚至被恶意构造分页、字段白名单、结果排序这些工程细节决定了这个接口能不能上生产。我试过在没做转义的情况下用户输入一个(就让接口直接 500所以转义这一步千万别省。下面从环境准备开始一步步把接口搭出来。2. TaoToken 前置准备给 Nodejs 模糊查询接口接上模型能力你可能会问写个模糊查询为什么还要提 TaoToken因为现在很多搜索接口不只是查数据库还要接大模型做语义补全、关键词改写、结果摘要。比如用户搜「便宜的手机」你可以先用模型把意图转成结构化关键词再去数据库做正则匹配。这时候就需要一个稳定的模型调用入口。TaoToken 在这里扮演的是统一 API 网关的角色它把模型对话、Coding Plan、API Keys 管理这些能力集中到一个控制台里。对 Nodejs 后端来说你只需要拿到一个 Base URL 和一个 Key就能在 Express 路由里发起模型请求不用分别对接多家厂商的 SDK。具体要准备三样东西我把它列成表格方便你对照项目值说明Base URLhttps://taotoken.net/api所有模型请求的统一入口注意不要加多余路径API Key在控制台创建形如sk-开头放在请求头里Model ID按需选择比如对话类、代码类模型填控制台里显示的准确 ID获取 Key 的入口在控制台的 API Keys 页面地址是https://taotoken.net/console/api-keys。创建之后复制保存因为它只完整显示一次。如果你只是想先验证模型能不能通可以用模型对话页面直接试地址是https://taotoken.net/model-chat。长期做编码和 Agent 任务的话Coding Plan 会更划算入口在https://taotoken.net/coding-plan。在 Express 项目里我一般把 Key 放在环境变量不写进代码# .env 文件 TAOTOKEN_API_KEYsk-你的key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后用dotenv加载// app.js require(dotenv).config(); const TAOTOKEN_API_KEY process.env.TAOTOKEN_API_KEY; const TAOTOKEN_BASE_URL process.env.TAOTOKEN_BASE_URL;这样做的原因是Key 一旦提交到 Git 仓库就等于泄露。环境变量是最低成本的隔离方式。等你把模糊查询接口写完如果想让搜索更智能就可以在路由里加一段调用模型的逻辑把用户输入先做一次关键词抽取再交给 Mongoose 查询。这一步不是必须的但能让你的搜索体验上一个台阶。需要提醒的是TaoToken 是模型能力的接入层不是数据库也不替代你的 Express 服务。模糊查询的主体逻辑还是在 Mongoose 这边模型只是锦上添花。别把两者搞混否则架构会乱。3. 可复制配置Express 路由 Mongoose 正则查询完整代码这一节是核心我直接把能跑的代码贴出来。假设你有一个商品集合字段包括name、category、price。目标是实现GET /api/products?keyword苹果page1limit10这样的接口。先看 Mongoose 模型定义// models/Product.js const mongoose require(mongoose); const productSchema new mongoose.Schema({ name: { type: String, required: true, index: true }, category: { type: String, default: }, price: { type: Number, default: 0 }, createdAt: { type: Date, default: Date.now } }); module.exports mongoose.model(Product, productSchema);注意name字段加了index: true。模糊查询如果数据量大没索引会全表扫描慢得离谱。虽然正则前缀匹配才能用上索引但加上总比不加好。接下来是正则转义函数这是很多人忽略的一步// utils/escapeRegex.js function escapeRegex(text) { return text.replace(/[.*?^${}()|[\]\\]/g, \\$); } module.exports escapeRegex;这个函数把正则里的特殊字符全部转义。比如用户输入a.b不转义的话.会匹配任意字符结果就不准了输入(甚至会直接让new RegExp抛异常。然后是路由部分// routes/products.js const express require(express); const router express.Router(); const Product require(../models/Product); const escapeRegex require(../utils/escapeRegex); router.get(/api/products, async (req, res) { try { const { keyword , page 1, limit 10 } req.query; const pageNum Math.max(parseInt(page, 10) || 1, 1); const limitNum Math.min(Math.max(parseInt(limit, 10) || 10, 1), 50); const skip (pageNum - 1) * limitNum; const query {}; if (keyword.trim()) { const safeKeyword escapeRegex(keyword.trim()); const reg new RegExp(safeKeyword, i); query.$or [ { name: { $regex: reg } }, { category: { $regex: reg } } ]; } const [list, total] await Promise.all([ Product.find(query).sort({ createdAt: -1 }).skip(skip).limit(limitNum).lean(), Product.countDocuments(query) ]); res.json({ code: 0, data: { list, total, page: pageNum, limit: limitNum, totalPages: Math.ceil(total / limitNum) } }); } catch (err) { console.error([products search error], err); res.status(500).json({ code: 500, message: 查询失败请稍后重试 }); } }); module.exports router;几个关键设计说明$or让关键词同时匹配name和category用户搜「数码」既能命中分类也能命中商品名。lean()返回纯 JS 对象省去 Mongoose 文档包装列表接口性能更好。Promise.all并行查列表和总数比串行快。limit做了上限 50 的保护防止有人传limit999999把服务拖垮。如果你用的是 TypeScript模型和路由的类型定义要补上但查询逻辑完全一致。另外如果你的项目里已经接了 TaoToken可以在keyword处理前加一步模型改写// 可选用模型把自然语言转成关键词 async function rewriteKeyword(raw) { const resp await fetch(${process.env.TAOTOKEN_BASE_URL}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${process.env.TAOTOKEN_API_KEY} }, body: JSON.stringify({ model: 你的模型ID, messages: [ { role: system, content: 把用户搜索词提炼成不超过3个关键词用空格分隔只输出关键词。 }, { role: user, content: raw } ] }) }); const data await resp.json(); return data.choices?.[0]?.message?.content?.trim() || raw; }这段是可选的但如果你做的是电商搜索用户输入往往很口语化先改写再查命中率会高不少。注意模型 ID 要填控制台里显示的准确值Base URL 用https://taotoken.net/api不要多加斜杠。4. 验证请求用 Postman 跑通模糊查询并确认返回结果代码写完了得验证。我用 Postman 演示你也可以用 curl 或浏览器直接访问。先启动服务node app.js # 或者用 nodemon npx nodemon app.js假设服务跑在http://localhost:3000。在 Postman 里新建一个 GET 请求GET http://localhost:3000/api/products?keyword苹果page1limit5点击 Send预期返回结构如下{ code: 0, data: { list: [ { _id: ..., name: 红富士苹果 5斤, category: 水果, price: 29.9 }, { _id: ..., name: 苹果手机壳, category: 数码配件, price: 19.9 } ], total: 2, page: 1, limit: 5, totalPages: 1 } }如果list里有数据说明模糊查询生效了。再测几个边界情况第一关键词为空。请求GET /api/products不带keyword应该返回全部数据因为query是空对象。第二关键词带特殊字符。请求keyworda.b如果转义正确只会匹配真正包含a.b的记录不会匹配axb。你可以先在数据库里插一条name: a.b测试和一条name: axb测试然后搜索a.b看是不是只返回第一条。第三大小写不敏感。插入name: iPhone 15搜索keywordiphone应该能命中因为用了i标志。第四分页。请求page2limit5看skip是否正确totalPages是否合理。用 curl 的话命令是这样curl http://localhost:3000/api/products?keyword%E8%8B%B9%E6%9E%9Cpage1limit5注意中文要 URL 编码Postman 会自动处理curl 手动测的时候别忘了。验证通过后建议把这几条测试用例固化到你的接口测试里用 Jest supertest 都行。搜索接口最容易在边界输入上出问题提前覆盖能省很多线上排查时间。5. 常见报错排查清单401、local proxy failed、reading choices 怎么解这一节把我遇到过和读者反馈过的报错集中列一下对照着查。报错一SyntaxError: Invalid regular expression: /(/: Unterminated group原因用户输入了未转义的(。解决确保所有用户输入都过escapeRegex。这个错误在没做转义的代码里必现属于高频坑。报错二401 Unauthorized或invalid api key如果你在搜索接口里调了 TaoToken 的模型接口这个报错说明 Key 不对或没带上。检查三点请求头是不是Authorization: Bearer sk-xxxKey 有没有多余空格环境变量有没有加载成功。可以在代码里打印process.env.TAOTOKEN_API_KEY?.slice(0, 6)确认前几位。报错三local proxy failed或连接超时这类报错通常出现在请求模型接口时。先确认 Base URL 写的是https://taotoken.net/api没有拼错或多加路径。然后检查你的服务器出网是否正常Nodejs 里可以用fetch或axios单独测一下连通性。如果是本地开发环境注意别把localhost和线上地址搞混。报错四Cannot read properties of undefined (reading choices)这个报错说明模型返回结构和你预期的不一样。常见原因是请求体格式不对或者模型 ID 填错了导致返回了错误对象。排查方法把resp.json()的结果完整打印出来看error字段。正确返回里才有choices数组。另外如果用了流式输出但按非流式解析也会读不到choices。报错五MongooseError: Operation products.find() buffering timed out这是数据库没连上。检查mongoose.connect的 URI 是否正确MongoDB 服务是否启动。模糊查询本身没问题是连接层的事。报错六查询结果为空但数据库明明有数据先确认字段名拼写Mongoose 是大小写敏感的。再确认$regex有没有写错层级正确写法是{ name: { $regex: reg } }不是{ name: reg }虽然后者有时也能用但不规范。最后检查关键词有没有被trim掉或者转义后变成了空字符串。报错七CastError: Cast to ObjectId failed如果你在查询里混入了_id条件而用户传的不是合法 ObjectId就会报这个。搜索接口一般不需要按_id模糊查去掉即可。把这份清单存下来下次报错先对号入座能省不少时间。核心原则就一条用户输入永远不可信转义、限长、白名单一个都别少。6. 把模糊查询接进真实项目分页、索引与模型增强的落地建议代码跑通只是第一步真正上线还要考虑几件事。第一索引策略。MongoDB 的正则查询只有前缀匹配比如^苹果才能用上普通索引。如果你做的是包含匹配苹果出现在任意位置索引基本帮不上忙数据量大了就得考虑全文索引或者搜索引擎。MongoDB 自带 text index可以支持分词搜索但中文分词效果一般。数据量到百万级建议上 Elasticsearch 或 MeilisearchMongoose 这边只做数据同步。第二字段白名单。别让用户指定搜哪个字段否则容易被构造出全字段扫描。我上面的代码固定搜name和category就是白名单思路。如果确实需要动态字段也要用一个允许的字段数组做校验。第三关键词长度限制。用户传一个 10000 字的字符串进来正则编译和匹配都会很慢。加一个keyword.slice(0, 50)之类的截断或者直接返回参数错误。第四模型增强的边界。用 TaoToken 做关键词改写时要设置超时和降级。模型接口挂了不能影响搜索主流程所以用try/catch包住失败就用原始关键词查。这样即使模型服务抖动用户至少还能搜到东西。第五返回字段控制。列表接口别把整条文档都返回用.select(name category price)只取需要的字段减少传输量。如果前端需要高亮可以在返回时用正则把匹配部分包上em标签但要注意 XSS前端渲染时用dangerouslySetInnerHTML要谨慎。最后说下接入文档的位置如果你要查 TaoToken 的完整接口说明在https://taotoken.net/doc。API Keys 管理在https://taotoken.net/console/api-keys。需要长期跑编码和 Agent 任务的话Coding Plan 入口是https://taotoken.net/coding-plan。这些地址记一下配环境的时候直接用。模糊查询这件事代码本身不复杂难的是把边界情况都考虑到。你把转义、分页、索引、降级这四件事做扎实这个搜索接口就能扛住真实流量了。