MongoServerError正则表达式无效UTF-8错误排查求助

问题描述 #

在使用正则表达式查询MongoDB数据库以忽略字段中的变音符号时，触发错误：
MongoServerError: Regular expression is invalid: UTF-8 error: byte 2 top bits not 0x80

需要确认正则表达式是否存在问题、报错的可能原因，以及可行的解决方案。

补充说明 #

通过PayloadCMS本地API直接调用mongoose，报错并非100%触发，有时正常有时失败，暂未定位到明确触发条件。

相关代码 #

查询逻辑 #

const cleanedQuery = removeDiacritics(query)
result = await payload.db.collections[collection].find(
  {
    [queryField]: {
      $regex: RegExp(cleanedQuery, 'i'),
    },
  },
  {
    _id: 1,
    [queryField]: 1,
  },
  {
    limit: 3,
  },
)

变音符号处理函数 #

function removeDiacritics(string = '') {
  return string
    .replace(/a/g, '[a,á,à,ä,â]')
    .replace(/A/g, '[A,a,á,à,ä,â]')
    .replace(/e/g, '[e,é,ë,è]')
    .replace(/E/g, '[E,e,é,ë,è]')
    .replace(/i/g, '[i,í,ï,ì]')
    .replace(/I/g, '[I,i,í,ï,ì]')
    .replace(/o/g, '[o,ó,ö,ò]')
    .replace(/O/g, '[O,o,ó,ö,ò]')
    .replace(/u/g, '[u,ü,ú,ù]')
    .replace(/U/g, '[U,u,ü,ú,ù]')
}

报错原因分析 #

1. 变音处理函数的逻辑缺陷：当前removeDiacritics仅替换基础英文字符（a/A/e/E等），如果用户输入本身包含带变音的字符（比如á），这些字符不会被处理，直接进入正则表达式。若输入存在不完整的UTF-8字节（比如截断的多字节字符），就会导致MongoDB解析正则时触发UTF-8编码错误。
2. MongoDB的正则UTF-8严格校验：MongoDB要求正则表达式必须是合法的UTF-8编码，当处理后的字符串中存在无效字节序列时，就会抛出该错误。
3. 偶发触发的可能原因：当query参数包含特殊字符、不完整的UTF-8字符，或者PayloadCMS传递参数时出现编码截断，才会触发报错，其他正常输入则能正常执行。

可行解决方案 #

方案1：使用Unicode规范化移除变音符号（推荐） #

替换原removeDiacritics函数，通过Unicode规范化自动移除所有变音符号，避免手动替换的遗漏：

function removeDiacritics(string = '') {
  // NFD规范化：将带变音的字符拆分为基础字符+变音标记，再移除变音标记
  return string.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
}

之后查询逻辑保持不变，此时cleanedQuery为纯基础字符，配合$regex的i选项即可匹配带变音的字段内容。

方案2：利用MongoDB的Collation特性（更优） #

如果需要直接让MongoDB忽略变音符号和大小写，无需手动处理输入，可给字段创建带Collation的索引，查询时指定相同的Collation：

// 第一步：给目标字段创建带Collation的索引（仅需执行一次）
await payload.db.collections[collection].createIndex(
  { [queryField]: 1 },
  { collation: { locale: 'en', strength: 2 } }
);

// 第二步：执行查询时指定相同的Collation
result = await payload.db.collections[collection]
  .find(
    { [queryField]: { $regex: query, 'i' } },
    { _id: 1, [queryField]: 1 }
  )
  .collation({ locale: 'en', strength: 2 })
  .limit(3);

Collation强度说明：

• strength: 1：忽略大小写、变音符号和重音
• strength: 2：忽略大小写和变音符号（常用）
• strength: 3：严格匹配（默认）

方案3：校验输入的UTF-8合法性 #

在处理查询前先过滤无效的UTF-8字符，避免非法输入触发报错：

// 校验UTF-8合法性的工具函数
function isValidUTF8(str) {
  try {
    encodeURIComponent(str);
    return true;
  } catch {
    return false;
  }
}

// 业务逻辑中加入校验
if (!isValidUTF8(query)) {
  // 处理无效输入，比如返回空结果
  result = [];
} else {
  const cleanedQuery = removeDiacritics(query);
  result = await payload.db.collections[collection].find(
    { [queryField]: { $regex: RegExp(cleanedQuery, 'i') } },
    { _id: 1, [queryField]: 1 }
  ).limit(3);
}

内容的提问来源于stack exchange，提问作者borisgrigorov