$substrCP是MongoDB按Unicode代码点安全截取字符串的聚合操作符，专为正确处理中文、emoji等多字节字符设计；而$substr已弃用且等价于$substrBytes，按字节截取易导致乱码。
$substrCP 是什么，为什么不能只用 $substr
$substrCP 是 MongoDB 从 3.4 起引入的聚合操作符，专门用于按 Unicode 代码点（code point）截取字符串。它和 $substr、$substrBytes 的根本区别在于单位：前者数“字符”，后两者分别按“字节”或已弃用的模糊单位处理。
中文、emoji、带重音符号的字母（如 cafétéria 中的 é）在 UTF-8 下可能占 2~4 字节，但都算作 1 个代码点。$substr 或 $substrBytes 直接按字节偏移会切坏多字节字符，导致乱码或空字符串；而 $substrCP 才能安全地取“前 3 个汉字”或“用户名首字母”。
-
$substr：已不推荐，行为等价于$substrBytes，对中文取[$name, 0, 2]可能只拿到半个汉字 -
$substrBytes：明确按字节，适合纯 ASCII 场景，但无法处理中文/emoji 安全截取 -
$substrCP：唯一能正确处理 UTF-8 多字节字符的选项，参数中的索引和长度都以“字符”为单位
怎么写 $substrCP 表达式：参数顺序和常见错误
语法固定为 {$substrCP: [<string expression>, <code point index>, <code point count>]}，三个参数缺一不可，且顺序不能颠倒。
-
<string expression></string>必须是字符串类型表达式，比如"$name"、{"$concat": ["$first", " ", "$last"]}；若字段为空、不存在或值为null，整个结果为"" <code point index>必须 ≥ 0，负数直接报错（不是返回空字符串），超长（比如索引大于字符串实际字符数）也返回""<code point count>必须 ≥ 0，若为 0 返回空字符串；若大于剩余字符数，自动截到末尾，不会报错
错误示例：{$substrCP: ["$name", -1, 3]} → 报错；{$substrCP: ["$name", 0, -3]} → 报错；{$substrCP: ["$name", 5, 10]}（但 $name 只有 4 个字符）→ 返回 ""。
实战场景：取首字母、去前后字符、动态长度截取
真实业务中很少只是“固定截 2 位”，更多是条件性操作。这些必须搭配其他操作符组合使用。
- 取姓名首字符：
{$substrCP: ["$name", 0, 1]} - 去掉字符串首字符（如清理前缀
"user_"）：{$substrCP: ["$username", 5, {"$strLenCP": "$username"}]}，注意这里用$strLenCP而非$strLenBytes - 截取最后 3 个字符：
{$substrCP: ["$path", {"$subtract": [{"$strLenCP": "$path"}, 3]}, 3]}，必须先算总长度再减，不能硬写负数索引 - 安全拼接 + 截取：比如把
"v"和版本号合并后再取前 10 位：{$substrCP: [{"$concat": ["v", "$version"]}, 0, 10]}
容易被忽略的兼容性和性能点
$substrCP 在 3.4+ 全版本支持，但要注意：它只能用在聚合管道中（$project、$addFields、$set 等阶段），**不能用在查询谓词（find() 的 $where 或普通 filter）里**。
- 性能上，
$substrCP比$substrBytes开销略高，因为要解析 UTF-8 序列，但对常规字段影响微乎其微；真正慢的是嵌套调用，比如在$substrCP内部又套一层$cond+$strLenCP计算长度 - 调试时如果结果为空，优先检查：字段是否存在、是否为字符串类型、索引是否越界、是否误用了
$substr替代$substrCP - 没有“从右往左截”的原生语法，所有反向操作都得靠
$strLenCP和$subtract算起始位置，这点比 SQL 的SUBSTR(..., -3)更显式也更易错
