1. mongoose unique 不生效的真实场景：为什么重复数据还能插进去
你给 schema 里的字段加了unique: true，满心以为数据库会帮你挡住重复值，结果连着插两条一模一样的手机号，居然都成功了，控制台连个警告都没有。这个坑我踩过不止一次，后来才彻底搞明白：mongoose 的 unique 根本不是校验器，它只是让 mongoose 在后台帮你建一个唯一索引。
这句话是整个问题的核心。很多人把unique: true和required: true、min、max归为一类，以为它们都在save()或create()的时候做数据校验。实际上required这类是 mongoose 在应用层跑的验证逻辑，而unique是交给 MongoDB 的索引层去保证的。两者的执行时机、报错方式、生效条件完全不同。
具体来说，当你写下phone: { type: String, unique: true }，mongoose 在初始化 model 的时候会尝试执行一次createIndex，在phone字段上建一个唯一索引。只有这个索引真正建成功了，重复插入才会被 MongoDB 拒绝，抛出E11000 duplicate key error。如果索引没建成功、或者根本没触发建索引，那unique就是一句空话，数据库层面没有任何约束，重复数据自然畅通无阻。
那索引为什么没建成功？常见原因有这么几个。第一，你改了 schema 之后没有重启应用，mongoose 只在 model 首次编译时尝试建索引，热更新不会重新触发。第二，集合里已经存在重复数据，MongoDB 拒绝在有重复值的字段上建唯一索引，建索引直接失败，但 mongoose 默认可能把错误吞掉或者只打一条日志。第三，autoIndex被关掉了，生产环境很多人为了性能把autoIndex: false，这时候 mongoose 压根不会自动建索引，得你手动建。第四，字段类型不一致，比如有的存字符串"123"，有的存数字123，索引建了也挡不住你以为的"重复"。
这篇就围绕"mongoose 设置 unique 不生效"这个典型场景，把 schema 定义、索引查看、索引重建、重复数据验证这一整条链路走一遍。适合正在用 Node.js + mongoose 做后端、被唯一约束坑过、想彻底搞清楚索引机制的同学。下面所有命令和代码都可以直接复制到你的项目里跑。
2. TaoToken 前置准备：把模型接入和调试环境先搭好
排查这类问题，光靠猜是不行的，你得有一个能快速验证、能反复试错的开发环境。我自己的习惯是，写 mongoose 相关的调试脚本时，顺手把大模型接入也配好，遇到报错直接让模型帮我分析日志，效率高很多。这里先把 TaoToken 的接入方式说清楚，后面排查过程中如果遇到看不懂的报错，你可以直接拿它来问。
TaoToken 是一个模型调用平台，官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。它做的事情很简单：给你一个统一的接口，用同一套 Key 就能调用不同的模型，不用每个模型单独去申请、单独去配环境。对于咱们这种要边写代码边查错的场景，挺省事。
先说拿 Key 的步骤。打开控制台 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console ，登录之后进到 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys ，新建一个 Key，复制出来存好。这个 Key 就是你后面所有请求的凭证，别泄露。
拿到 Key 之后，怎么用？如果你只是想快速问个问题、贴段报错让模型看看，直接用模型对话页面就行： https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat 。把 mongoose 的报错日志、你的 schema 定义贴进去，让它帮你判断是索引没建还是数据重复。
如果你是要长期写代码、跑 Agent 任务，那更适合用 Coding Plan： https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan 。它针对编码场景做了优化，配合编辑器插件用起来比较顺。
接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc ，里面有各个语言、各个工具的配置示例。Claude Code 相关的接入看 https://taotoken.net/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode 。
这里要强调一点：TaoToken 是帮你调用模型的工具，它不替代你的编辑器，也不替代 MongoDB。排查 mongoose 索引问题，核心还是靠你自己在数据库里查、在代码里试，模型只是帮你加速理解报错。别指望配个 Key 问题就自动没了。
配置的时候记住三件套：Base URL、API Key、Model ID。这三个东西缺一不可，后面第五节讲报错排查时会反复用到。Base URL 用 https://taotoken.net/api ，Key 就是你刚建的那个，Model ID 按文档里写的填。把这三个配对了，模型调用基本不会出问题。
3. 可复制的 schema 定义与索引配置：从根上避免 unique 失效
这一节是重点，我把一个完整可跑的 schema 定义给你，包含唯一约束、索引配置、以及几个容易踩坑的细节。你直接复制到项目里，改改字段名就能用。
先看 schema 定义。假设我们做一个用户表，手机号要求唯一：
// models/User.js const mongoose = require('mongoose'); const userSchema = new mongoose.Schema( { name: { type: String, required: true, }, phone: { type: String, unique: true, // 关键：唯一约束 required: true, trim: true, // 去掉首尾空格，避免 "123 " 和 "123" 被当成不同值 }, email: { type: String, unique: true, sparse: true, // 允许 email 为空，空值不参与唯一性判断 lowercase: true, trim: true, }, age: { type: Number, default: 18, }, }, { versionKey: false, timestamps: { createdAt: 'createTime', updatedAt: 'updateTime' }, autoIndex: true, // 确保自动建索引，生产环境要谨慎 } ); module.exports = mongoose.model('User', userSchema);这段代码里有几个点值得展开说。
unique: true只是声明，真正建索引靠的是 mongoose 启动时的createIndex。autoIndex: true是默认值，但如果你在连接配置里全局关掉了，这里写 true 也没用，得看连接层的设置。所以更稳妥的做法是，在连接数据库的时候显式确认：
// db.js const mongoose = require('mongoose'); async function connectDB() { await mongoose.connect('mongodb://127.0.0.1:27017/testdb', { autoIndex: true, // 开发环境打开，方便自动建索引 }); console.log('MongoDB connected'); } module.exports = connectDB;sparse: true这个选项很多人不知道。默认情况下，唯一索引会把null也当成一个值，也就是说你只能有一条 email 为空的记录，第二条就报重复了。加上sparse: true之后，字段不存在的文档不参与索引，这样多条没有 email 的记录可以共存。这个坑在用户表里特别常见。
trim: true和lowercase: true是数据规范化。如果不加，"ABC@qq.com"和"abc@qq.com"会被当成两个不同的值，唯一索引挡不住。加上之后，存进去之前就统一了格式，唯一性才有意义。
还有一个历史遗留选项dropDups: true，你在老教程里可能见过。这个选项在 MongoDB 3.0 之后就被移除了，现在写上去没有任何作用，甚至可能报错。别再用它，重复数据要自己先清理掉再建索引。
如果你需要手动建索引，而不是靠 mongoose 自动建，可以这样写：
// 手动确保索引存在 async function ensureIndexes() { const User = require('./models/User'); await User.createIndexes(); // 根据 schema 建所有索引 // 或者只建某一个 // await User.collection.createIndex({ phone: 1 }, { unique: true }); console.log('索引创建完成'); }createIndexes()会读取 schema 里所有标记了index或unique的字段，逐个建索引。如果某个索引因为数据重复建失败，它会抛错，你就能看到具体是哪个字段、什么原因。这比默默失败强多了。
再给一个 JSON 格式的配置对照，方便你检查自己的项目：
{ "phone": { "type": "String", "unique": true, "required": true, "trim": true }, "email": { "type": "String", "unique": true, "sparse": true, "lowercase": true } }把这段和你自己的 schema 对一遍，看看有没有漏掉sparse、有没有写dropDups、autoIndex是不是被关了。大部分 unique 不生效的问题，都能在这几个配置里找到原因。
4. 验证请求与成功结果：用重复数据实测唯一约束是否真的生效
配置写好了，怎么确认它真的生效了？不能光看代码，得实际插数据试。这一节给你一套完整的验证流程，从查索引到插重复数据，一步步来。
第一步，先看索引到底建了没有。打开 MongoDB shell，或者用 mongosh：
use testdb db.users.getIndexes()正常的话，你会看到类似这样的输出：
[ { v: 2, key: { _id: 1 }, name: '_id_' }, { v: 2, key: { phone: 1 }, name: 'phone_1', unique: true }, { v: 2, key: { email: 1 }, name: 'email_1', unique: true, sparse: true } ]重点看unique: true这个标记。如果phone_1这个索引存在但没有unique: true，说明索引建了但不是唯一索引，那约束还是不生效。如果压根没有phone_1，说明索引没建，回到上一节检查autoIndex和createIndexes。
第二步，用代码插重复数据验证。写一个测试脚本：
// test-unique.js const mongoose = require('mongoose'); const connectDB = require('./db'); const User = require('./models/User'); async function testUnique() { await connectDB(); // 先清空，保证测试环境干净 await User.deleteMany({}); // 插第一条 await User.create({ name: '张三', phone: '13800000000' }); console.log('第一条插入成功'); // 插第二条，phone 相同 try { await User.create({ name: '李四', phone: '13800000000' }); console.log('第二条也插入成功了 —— unique 没生效！'); } catch (err) { if (err.code === 11000) { console.log('第二条被拒绝，unique 生效，错误码 11000'); console.log('重复的字段：', err.keyValue); } else { console.log('其他错误：', err.message); } } await mongoose.disconnect(); } testUnique();跑这个脚本，如果输出"第二条被拒绝，unique 生效，错误码 11000"，那就说明配置对了。如果输出"第二条也插入成功了"，那说明索引没建或者不是唯一索引，回去查。
err.code === 11000是 MongoDB 重复键错误的标准错误码，记住它。以后在业务代码里捕获这个错误，就能给用户返回"手机号已注册"之类的提示：
try { await User.create({ name, phone }); } catch (err) { if (err.code === 11000) { return res.status(400).json({ msg: '手机号已被注册' }); } throw err; }第三步，验证sparse是否生效。插两条 email 为空的记录：
await User.create({ name: '王五', phone: '13800000001' }); await User.create({ name: '赵六', phone: '13800000002' }); console.log('两条无 email 记录都插入成功，sparse 生效');如果这里报重复键错误，说明sparse没配，或者索引建的时候没带sparse选项。注意，sparse是建索引时的属性，改了 schema 之后必须重建索引才生效，光改代码没用。
第四步，如果你已经有一堆重复数据，想清理之后再建唯一索引，可以这样操作：
// 找出重复的 phone db.users.aggregate([ { $group: { _id: '$phone', count: { $sum: 1 } } }, { $match: { count: { $gt: 1 } } } ])这条聚合会列出所有重复的 phone 和它们的数量。根据结果决定保留哪条、删哪条。清理完之后，再执行User.createIndexes()重建索引，这次就能成功了。
实测下来，只要索引建对了，重复插入必然被挡。如果还被放进去，那一定是索引的问题，不是 mongoose 的问题。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 逐个拆
排查过程中会遇到各种报错，有些是 mongoose 的，有些是模型调用环境的。这一节把常见的几个列出来，对照着看。
报错一：E11000 duplicate key error
这是唯一约束生效时的正常报错，不是 bug。完整信息类似：
MongoServerError: E11000 duplicate key error collection: testdb.users index: phone_1 dup key: { phone: "13800000000" }看到这个说明索引建对了，重复数据被挡住了。你要做的是在业务代码里捕获err.code === 11000，转成友好的提示。如果不想让它抛错，可以在插入前先查一次，但注意并发场景下查了再插仍有竞态，最终还是得靠唯一索引兜底。
报错二：401 Unauthorized
这个通常出现在调用模型接口的时候，不是 mongoose 的问题。原因一般是 API Key 没填对、填了但过期了、或者 Base URL 配错了。检查三件套：Base URL 是不是https://taotoken.net/api，Key 是不是从 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys 复制的最新那个，Model ID 是不是文档里写的。三个都对上，401 基本就没了。
报错三：local proxy failed
这个报错一般和网络环境有关，提示本地代理失败。检查你的请求是不是走了不该走的代理配置，把代理关掉，直连https://taotoken.net/api再试。如果你在代码里设置了HTTP_PROXY之类的环境变量，先清掉。
报错四：reading choices
这个报错通常出现在解析模型返回结果的时候，提示读取choices字段失败。原因是返回结构和你预期的不一样，可能是请求没成功、返回的是错误信息而不是正常的 completion 结构。打印完整的返回体看看，确认请求是否真的成功了。如果用的是 OpenAI 兼容格式，正常返回里应该有choices数组，没有的话就是上游出错了。
报错五：OAuth 相关错误
如果你在用 Claude Code 或者某些需要 OAuth 授权的工具，可能会遇到 OAuth 报错。检查你的授权配置，确认用的是正确的接入方式。Claude Code 的接入参考 https://taotoken.net/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=claudecode ，按文档里的步骤配。
报错六：索引建了但 unique 不生效
这个最隐蔽。getIndexes()里明明有phone_1，但没有unique: true。原因是之前建过一次非唯一索引，后来改了 schema 加unique，但 MongoDB 不会自动把已有索引改成唯一索引。解决办法是先删掉旧索引再重建：
await User.collection.dropIndex('phone_1'); await User.createIndexes();或者干脆把整个集合的索引清掉重建。记住，索引的属性（unique、sparse）在创建时就固定了，改 schema 不会自动更新已有索引。
报错七：CC Switch / Cline MCP / Codex auth.json 配置问题
如果你在用这些工具，配置的时候同样要写全三件套。以 Codex 的auth.json为例，里面要包含 Base URL、API Key、Model ID 三个字段，缺一个都会导致调用失败。Cline 的 MCP 配置也是同理，Base URL 填https://taotoken.net/api，Key 填你的，Model ID 按文档填。CC Switch 切换配置的时候，确认切换后的配置里这三项都完整。
排查的核心思路就一条：先确认索引建对了，再确认数据没重复，最后确认调用环境配对了。按这个顺序走，大部分问题都能定位到。
6. 语义一致收尾：把 unique 当成索引而不是校验器
回到最开始那句话：mongoose 的unique是索引层面的约束，不是应用层的校验器。理解这一点，很多困惑就解开了。
它不会在save()之前帮你查一遍数据库，它只是让 MongoDB 在写入时用唯一索引挡住重复。所以索引没建，约束就不存在。索引建了但不是唯一的，约束也不存在。索引建对了但数据里有重复，索引根本建不起来。
我自己的习惯是，每次改完 schema 里跟unique、index相关的字段，都跑一遍User.createIndexes()，然后去getIndexes()里确认一眼。开发环境把autoIndex打开，生产环境手动建索引并做好监控。重复数据在插入前用业务逻辑挡一道，数据库层再用唯一索引兜底，两层配合才稳。
如果你在排查过程中遇到看不懂的报错，把日志贴到模型对话里让它帮你分析，比自己盯着看快。接入方式前面都给了，Key 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys 建，文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc 看。长期写代码的话，Coding Plan 那个入口 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan 更适合。
最后留一个实用技巧：在 model 文件里加一段启动时的索引检查日志，每次应用启动都打印一下当前集合的索引情况。这样索引一旦出问题，你第一时间就能发现，不用等到用户反馈重复数据了才去查。
User.collection.getIndexes().then((indexes) => { console.log('当前索引：', JSON.stringify(indexes, null, 2)); });把这段放在连接数据库之后，简单直接，能省掉很多排查时间。
