1. MongoDB 分页查询为什么越翻越慢从 skip/limit 到游标分页的真实场景MongoDB 分页查询是后端开发里最容易被低估的一环。刚上线时数据量小skip().limit()一把梭翻到第几页都毫秒级返回等集合涨到几百万行用户点一下「下一页」接口直接卡三秒CPU 飙高慢查询日志里全是COLLSCAN。这不是数据库不行而是分页姿势从一开始就选错了。先把三种主流分页方式摆清楚你对着自己的业务场景挑分页方式核心写法适用场景主要问题偏移分页skip(n).limit(m)后台小数据量、跳页需求深翻页线性变慢skip 越大越慢游标分页find({_id: {$gt: lastId}}).limit(m)信息流、无限滚动、导出不能随机跳页范围分页find({createTime: {$lt: lastTime}}).limit(m)按时间倒序的列表时间重复时需复合游标skip慢的根因在于MongoDB 执行skip(100000).limit(20)时并不是「直接跳到第 10 万条」而是老老实实扫描并丢弃前 10 万条文档再取 20 条。数据量越大被丢弃的越多耗时随页码线性增长。我试过在一个 800 万行的日志集合上翻到第 5000 页单次查询 4.2 秒换成游标分页后稳定在 8 毫秒以内。游标分页的思路是「记住上一页最后一条的位置」下一页从那个位置往后取天然走索引不扫描历史数据。代价是不能跳到任意页但对信息流、消息列表、数据导出这类「只往后翻」的场景完全够用。这篇要解决的完整链路是分页查询怎么写才不慢、索引怎么建才走得到、排序怎么保证稳定不重复不漏数据以及怎么用 TaoToken 的统一 Key 和 API 通道把查询服务接起来让本地调试、线上服务、脚本导出共用一套凭证不用在多个 Key 之间来回切换。适合正在做列表接口、数据导出、后台管理的 Node.js / Mongoose 开发者也适合想把 AI 查询助手接进自己数据服务的人。2. TaoToken 统一 Key 前置准备一个 Key 打通查询服务与 AI 通道分页查询本身是数据库的事为什么要在前面加一层 TaoToken因为真实项目里查询服务往往不止被前端调用还要被 AI 助手、数据看板、定时导出脚本调用。如果每个调用方各自维护一套模型 Key 和 API 地址配置散落各处排查问题时连「这个请求到底走的哪个通道」都说不清。TaoToken 在这里扮演的是统一入口一个 Key、一个 Base URL既能调模型对话也能作为查询服务的上游通道。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置时别把推广参数拼进去。前置准备分三步都是几分钟的事第一步拿到 Key。进入控制台创建 API Key路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建后立刻复制保存页面刷新后不再完整显示。Key 的形态是一串以sk-开头的字符串。第二步确认要用的模型 ID。如果你只是把 TaoToken 当查询服务的统一通道模型 ID 按你实际调用的填如果还要接 AI 查询助手去模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 看当前可用的模型列表把 ID 抄下来后面配置里要用。第三步把 Key 写进环境变量不要硬编码进代码。这是踩过的坑早期图省事把 Key 写在config.js里提交到了仓库后来只能全部轮换。正确做法是# .env 文件加入 .gitignore TAOTOKEN_API_KEYsk-你的实际Key TAOTOKEN_BASE_URLhttps://taotoken.net/api// config.js require(dotenv).config(); module.exports { taoToken: { apiKey: process.env.TAOTOKEN_API_KEY, baseUrl: process.env.TAOTOKEN_BASE_URL, model: claude-sonnet-4-5 // 按模型对话页实际可用 ID 填写 }, mongo: { uri: process.env.MONGO_URI || mongodb://127.0.0.1:27017/demo } };如果你用的是 Claude Code 这类编码工具想让 AI 直接帮你写分页查询可以走 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 长期编码和 Agent 场景用这个更划算。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数不确定时以文档为准。这里要强调一个原则TaoToken 是统一 Key 和 API 通道不是数据库代理也不是编辑器替代品。它解决的是「凭证和通道统一」的问题MongoDB 的连接、索引、查询语句还是你自己写。把这两层分清楚后面配置才不会乱。3. 可复制的分页查询配置Mongoose 模板 索引 settings 片段这一节给可直接粘贴的代码。先建索引再写分页函数最后给统一通道的配置文件。3.1 索引配置让分页走得到索引游标分页要快排序字段必须有索引且索引顺序要和查询条件、排序方向一致。假设按createTime倒序分页// models/Article.js const mongoose require(mongoose); const ArticleSchema new mongoose.Schema({ title: { type: String, required: true }, content: { type: String, default: }, authorId: { type: mongoose.Schema.Types.ObjectId, ref: User }, createTime: { type: Number, default: () Date.now() }, status: { type: String, default: published } }, { versionKey: false }); // 关键索引查询条件 排序字段 _id 兜底保证排序稳定 ArticleSchema.index({ status: 1, createTime: -1, _id: -1 }); // 按作者查列表时用 ArticleSchema.index({ authorId: 1, createTime: -1, _id: -1 }); module.exports mongoose.model(Article, ArticleSchema);为什么索引里要带_id因为createTime可能重复同一毫秒写入多条只按createTime排序时重复值的相对顺序不稳定翻页会出现「同一条数据出现两次」或「某条数据被跳过」。把_id作为第二排序键排序就唯一了游标也才能精确定位。3.2 游标分页模板// services/pagination.js const Article require(../models/Article); /** * 游标分页按 createTime 倒序_id 兜底 * param {Object} params * param {string} params.status 状态过滤 * param {number} params.limit 每页条数建议 100 * param {Object} params.cursor 上一页返回的游标 { createTime, _id } */ async function pageByCursor({ status published, limit 20, cursor null }) { const query { status }; if (cursor cursor.createTime ! null cursor._id) { // 复合游标条件时间更早或时间相同但 _id 更小 query.$or [ { createTime: { $lt: cursor.createTime } }, { createTime: cursor.createTime, _id: { $lt: cursor._id } } ]; } const docs await Article.find(query) .sort({ createTime: -1, _id: -1 }) .limit(limit 1) // 多取一条判断是否还有下一页 .lean(); const hasMore docs.length limit; const list hasMore ? docs.slice(0, limit) : docs; const last list[list.length - 1]; return { list, hasMore, nextCursor: hasMore last ? { createTime: last.createTime, _id: last._id } : null }; } module.exports { pageByCursor };多取一条limit 1是判断hasMore的常用技巧比额外跑一次countDocuments便宜得多。countDocuments在大集合上本身就很慢能不用就不用。3.3 偏移分页模板保留跳页能力后台管理确实需要跳页时用skip/limit但加两个约束限制最大 skip超过就拒绝查询必须命中索引。async function pageByOffset({ status published, page 1, size 20 }) { const MAX_SKIP 10000; const skip (page - 1) * size; if (skip MAX_SKIP) { throw new Error(页码过深请使用游标分页或缩小筛选范围); } const [list, total] await Promise.all([ Article.find({ status }) .sort({ createTime: -1, _id: -1 }) .skip(skip) .limit(size) .lean(), Article.countDocuments({ status }) ]); return { list, total, page, size }; }3.4 统一通道 settings 片段把 TaoToken 的 Base URL、Key、Model ID 三件套写进配置查询服务和 AI 助手共用{ taoToken: { baseUrl: https://taotoken.net/api, apiKey: ${TAOTOKEN_API_KEY}, model: claude-sonnet-4-5, timeout: 30000 }, mongo: { uri: ${MONGO_URI}, options: { maxPoolSize: 20, serverSelectionTimeoutMS: 5000 } }, pagination: { defaultLimit: 20, maxLimit: 100, maxSkip: 10000 } }如果你用 Cline 或 MCP 方式接入配置里同样要写全 Base URL、Key、Model ID 三项缺一项就会报鉴权或模型找不到。API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 需要轮换或新建时从这里进。4. 验证请求与成功结果分页边界、性能对比与统一通道连通性配置写完必须验证分三块分页正确性、性能、通道连通性。4.1 分页边界验证写一个脚本连续翻 5 页检查有没有重复和遗漏// scripts/verify-pagination.js const mongoose require(mongoose); const config require(../config); const { pageByCursor } require(../services/pagination); (async () { await mongoose.connect(config.mongo.uri); const seen new Set(); let cursor null; let page 0; while (page 5) { const { list, hasMore, nextCursor } await pageByCursor({ status: published, limit: 20, cursor }); for (const doc of list) { const id String(doc._id); if (seen.has(id)) { console.error(发现重复数据:, id); } seen.add(id); } console.log(第 ${page 1} 页返回 ${list.length} 条hasMore${hasMore}); if (!hasMore) break; cursor nextCursor; page; } console.log(累计去重后 ${seen.size} 条); await mongoose.disconnect(); })();预期输出类似第 1 页返回 20 条hasMoretrue 第 2 页返回 20 条hasMoretrue 第 3 页返回 20 条hasMoretrue 第 4 页返回 20 条hasMoretrue 第 5 页返回 20 条hasMoretrue 累计去重后 100 条如果「累计去重后」小于「页数 × 每页条数」说明排序不稳定回去检查索引是否带了_id。4.2 性能对比验证用explain看执行计划确认走的是IXSCAN而不是COLLSCANconst explain await Article.find({ status: published }) .sort({ createTime: -1, _id: -1 }) .limit(20) .explain(executionStats); console.log(explain.executionStats.executionStages.stage); console.log(扫描文档数:, explain.executionStats.totalDocsExamined); console.log(返回文档数:, explain.executionStats.nReturned);健康的结果是totalDocsExamined接近nReturned比如扫描 20 返回 20。如果扫描了几十万才返回 20 条说明索引没命中检查索引字段顺序和查询条件是否匹配。4.3 统一通道连通性验证用 curl 验证 TaoToken 通道是否通curl -s -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 只回复两个字连通}] }返回里能看到content字段和正常文本就说明 Key、Base URL、Model ID 三件套都对。如果返回 401先查 Key 是否复制完整如果返回模型不存在去模型对话页核对 ID。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth分页查询和通道接入的报错按真实日志对照排查。报错一401 Unauthorized/invalid api key原因通常是 Key 没读到或复制不全。检查.env是否被dotenv正确加载process.env.TAOTOKEN_API_KEY打印出来是不是undefined。另一个常见原因是把 UTM 参数拼进了 API 地址正确地址是https://taotoken.net/api不带任何查询参数。修复后重启服务环境变量不会热更新。报错二local proxy failed/ 连接被拒绝这类报错多出现在本地网络配置或代理设置上。先确认TAOTOKEN_BASE_URL写的是https://taotoken.net/api没有多余斜杠或路径。再检查系统环境变量里有没有残留的HTTP_PROXY/HTTPS_PROXY指向失效地址有就清掉。Node 里可以用delete process.env.HTTP_PROXY临时排除。报错三reading choices/Cannot read properties of undefined这是解析响应结构时字段对不上。不同接口返回结构不同Anthropic 风格是content数组OpenAI 风格是choices数组。如果你按choices解析却拿到content结构就会读到undefined。修复方式是先打印完整响应体确认结构后再取字段const resp await fetch(${config.taoToken.baseUrl}/v1/messages, { /* ... */ }); const data await resp.json(); console.log(JSON.stringify(data, null, 2)); // 先看清结构 const text data.content?.[0]?.text ?? data.choices?.[0]?.message?.content ?? ;报错四OAuth相关鉴权失败如果你用的是 Claude Code 或 Codex 这类工具鉴权方式可能不是简单 API Key而是 OAuth 流程。这类工具接入时Base URL、Key、Model ID 三件套要写全缺一项就会在 OAuth 回调后报鉴权失败。Codex 的auth.json里要确认base_url指向https://taotoken.net/apiapi_key填实际 Key模型 ID 和模型对话页一致。Claude Code 的配置同理三件套缺一不可。报错五分页结果重复或漏数据回到索引检查。排序字段有重复值时必须加_id作为第二排序键查询条件里的游标也要用复合条件$or那段。只按createTime排序、游标只带createTime重复时间的数据就会乱序。报错六skip深翻页超时这是设计问题不是 bug。加MAX_SKIP限制超过就引导用户用游标分页或加筛选条件缩小范围。后台如果非要跳页考虑用「按时间范围筛选 游标」替代纯 skip。6. 把统一 Key 用起来查询服务、AI 助手与长期编码的分工分页查询写对了索引建对了通道配对了接下来是把这套东西用顺。日常调试查询逻辑时用模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 快速验证模型可用性把分页函数贴给 AI 让它帮你检查边界条件比人肉翻代码快。需要新建或轮换 Key 时走 API Key 管理页 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 参数细节以接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 为准。如果分页查询只是你项目里的一小块后面还要长期写代码、跑 Agent 任务Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 比按次调用更省心。Claude Code 接入走 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 配置时记住 Base URL、Key、Model ID 三件套写全。最后给一个实用技巧把分页的nextCursor直接返回给前端前端存起来下一页原样传回。这样前端不需要理解createTime和_id的组合逻辑后端改排序字段时前端也不用动。游标用 Base64 编码一下避免前端手抖改坏结构const encodeCursor (c) Buffer.from(JSON.stringify(c)).toString(base64); const decodeCursor (s) s ? JSON.parse(Buffer.from(s, base64).toString()) : null;这套组合跑下来800 万行的集合翻页稳定在 10 毫秒内索引扫描文档数和返回数基本持平统一 Key 让查询服务和 AI 助手共用一套凭证排查问题时链路清晰。