ReadPreferenceTags 是启用 MongoDB 标签级读路由的必需配置项；仅设 ReadPreference 为 secondary 或 nearest 无法保证请求落到指定标签节点，必须显式传入 readPreferenceTags 数组才能触发标签匹配。
ReadPreferenceTags 是什么，为什么不能只靠 ReadPreference
单纯设 ReadPreference 为 secondary 或 nearest，MongoDB 不会保证读请求落到你指定的节点类型上——比如你有带 "region": "cn" 和 "region": "us" 标签的副本节点，但默认策略可能把中国用户的读请求发到美国节点。这时必须配合 readPreferenceTags，它才是做「标签级路由」的开关。
关键点：标签本身不生效，readPreferenceTags 是显式启用标签匹配的配置项；没它，标签只是元数据。
怎么给副本集节点打标签并验证
标签必须在副本集配置中设置，且需重新加载配置（不是重启 mongod）。常见错误是改了 rs.conf() 但忘了 rs.reconfig()，或没加 { force: true } 处理主节点变更。
操作步骤：
- 连接到主节点，执行
cfg = rs.conf() - 给某个成员加标签：
cfg.members[1].tags = { "region": "cn", "type": "read" } - 提交配置：
rs.reconfig(cfg, { force: true }) - 验证是否生效：
rs.conf().members[1].tags应返回刚设的键值对
注意：标签键名不强制统一，但客户端代码里写的键必须和这里完全一致（包括大小写），否则匹配失败。
驱动端如何传 readPreferenceTags（以 Node.js 为例）
Node.js 驱动里，readPreferenceTags 是 ReadPreference 构造函数的第二个参数，不是独立选项。容易错写成拼错 key 名，比如写成 readPreferenceTags 当作连接字符串参数，实际它只在构造读策略时生效。
正确写法：
const { ReadPreference } = require('mongodb');
const readPref = new ReadPreference('secondary', [
{ region: 'cn' },
{ region: 'fallback' }
]);
// 然后传给 collection.find() 或 client.db().collection()
collection.find({}).readPreference(readPref).toArray();
说明：
- 数组内对象是「或」关系：匹配任一即可（比如先找
region: cn，找不到就用region: fallback） - 每个对象内是「与」关系：必须同时满足所有键值（如
{ region: 'cn', type: 'read' }） - 如果所有标签组合都无匹配节点，驱动会退回到默认
ReadPreference行为（比如降级到主节点读），不会报错
常见失效场景和排查思路
最常遇到的是「明明配了标签，读还是打到错误节点」。核心原因往往不是配置错，而是没理解标签匹配的触发前提。
排查重点：
- 确认当前连接的副本集状态正常：
rs.status().members中对应成员的stateStr必须是SECONDARY（标签只对可读节点生效） - 检查驱动版本：老版本（如 mongodb@3.x）对
readPreferenceTags支持不完整，建议升级到 4.15+ 或 5.x - 确认没有在更高优先级位置覆盖策略：比如 connection string 里写了
readPreference=primary，会直接忽略代码里的ReadPreference实例 - 日志里搜
no suitable servers found：这表示标签全不匹配且无 fallback，不是 bug，是预期行为
真正难调的是多层标签嵌套时的语义歧义，比如 { env: 'prod', region: 'cn' } 和 { env: 'prod' } 同时存在，驱动不会做子集匹配——必须字面完全一致才命中。
